Added table_of_content method (#55)

* Added `table_of_content` method

(aliased to `toc` and `table_of_contents`)

This returns an array of objects (`Perron::Resource::TableOfContent::Item id="", text="", level=n, children=[]`) of all headings in a resource's
content. It expects an `id` per heading, or, like commonmarker does, a
nested `a` element with an `id`.

* Standard fix

Author: eelcoj

lib/perron/resource.rb

@@ -9,6 +9,7 @@
 require "perron/resource/renderer"
 require "perron/resource/slug"
 require "perron/resource/separator"
+require "perron/resource/table_of_content"
 
 module Perron
   class Resource
@@ -18,6 +19,7 @@ class Resource
     include Perron::Resource::Core
     include Perron::Resource::ClassMethods
     include Perron::Resource::Publishable
+    include Perron::Resource::TableOfContent
 
     attr_reader :file_path, :id
 

lib/perron/resource/table_of_content.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Perron
+  class Resource
+    module TableOfContent
+      extend ActiveSupport::Concern
+
+      def table_of_content(levels: %w[h1 h2 h3 h4 h5 h6])
+        return [] if content.blank? || metadata.toc == false
+
+        document = Nokogiri::HTML::DocumentFragment.parse(Markdown.render(content))
+        headings = extract_headings from: document, levels: levels.join(", ")
+
+        Builder.new.build(headings)
+      end
+      alias_method :table_of_contents, :table_of_content
+      alias_method :toc, :table_of_content
+
+      private
+
+      Item = ::Data.define(:id, :text, :level, :children)
+
+      def extract_headings(from:, levels:)
+        from.css(levels).each_with_object([]) do |heading, headings|
+          heading.tap do |node|
+            heading_text = node.text.strip
+            id = node["id"] || node.at("a")&.[]("id")
+
+            next if heading_text.empty? || id.blank?
+
+            headings << Item.new(
+              id: id,
+              text: heading_text,
+              level: node.name[1..].to_i,
+              children: []
+            )
+          end
+        end
+      end
+
+      class Builder
+        def build(headings)
+          parents = {0 => {children: []}}
+
+          headings.each_with_object(parents[0][:children]) do |heading, _|
+            parents.delete_if { |level, _| level >= heading.level }
+
+            parent = parents[parents.keys.select { it < heading.level }.max || 0]
+
+            (parent.is_a?(Hash) ? parent[:children] : parent.children) << heading
+
+            parents[heading.level] = heading
+          end
+        end
+      end
+    end
+  end
+end

test/dummy/app/content/other/exclude-toc-resource.html

@@ -0,0 +1,22 @@
+---
+toc: false
+---
+
+<h1 id="main-heading">Main Heading</h1>
+
+Some content here
+
+
+<h2 id="section-one">Section One</h2>
+
+Content for section one
+
+
+<h3 id="subsection">Subsection</h3>
+
+More detailed content
+
+
+<h2 id="section-two">Section Two</h2>
+
+Final section content

test/dummy/app/content/other/toc-commonmarker.html

@@ -0,0 +1,30 @@
+<h1>
+  <a href="#main-heading" aria-hidden="true" class="anchor" id="main-heading"></a>
+  Main Heading
+</h1>
+
+Some content here
+
+
+<h2 id="section-one">
+  <a href="#section-one" aria-hidden="true" class="anchor" id="section-one"></a>
+  Section One
+</h2>
+
+Content for section one
+
+
+<h3 id="subsection">
+  <a href="#subsection" aria-hidden="true" class="anchor" id="subsection"></a>
+  Subsection
+</h3>
+
+More detailed content
+
+
+<h2 id="section-two">
+  <a href="#section-two" aria-hidden="true" class="anchor" id="section-two"></a>
+  Section Two
+</h2>
+
+Final section content

test/dummy/app/content/other/toc-resource.html

@@ -0,0 +1,18 @@
+<h1 id="main-heading">Main Heading</h1>
+
+Some content here
+
+
+<h2 id="section-one">Section One</h2>
+
+Content for section one
+
+
+<h3 id="subsection">Subsection</h3>
+
+More detailed content
+
+
+<h2 id="section-two">Section Two</h2>
+
+Final section content

test/perron/resource/table_of_content_test.rb

@@ -0,0 +1,84 @@
+require "test_helper"
+
+class Perron::Resource::TableOfContentTest < ActiveSupport::TestCase
+  setup do
+    page_path = "test/dummy/app/content/pages/about.md"
+    toc_resource_path = "test/dummy/app/content/other/toc-resource.html"
+    toc_commonmarker_path = "test/dummy/app/content/other/toc-commonmarker.html"
+    exclude_toc_resource_path = "test/dummy/app/content/other/exclude-toc-resource.html"
+
+    @page = Content::Page.new(page_path)
+    @toc_resource = Content::Page.new(toc_resource_path)
+    @toc_commonmarker = Content::Page.new(toc_commonmarker_path)
+    @exclude_toc_resource = Content::Page.new(exclude_toc_resource_path)
+  end
+
+  test "table_of_content returns empty array" do
+    toc = @page.table_of_content
+
+    assert_equal [], toc
+  end
+
+  test "table_of_content returns empty array when `toc: false`" do
+    toc = @exclude_toc_resource.table_of_content
+
+    assert_equal [], toc
+  end
+
+  test "table_of_content returns headings structure" do
+    toc = @toc_resource.table_of_content
+
+    assert_not_nil toc
+    assert_equal 1, toc.size
+
+    h1 = toc.first
+    assert_equal "main-heading", h1.id
+    assert_equal "Main Heading", h1.text
+    assert_equal 1, h1.level
+    assert_equal 2, h1.children.size
+
+    h2_one = h1.children.first
+    assert_equal "section-one", h2_one.id
+    assert_equal "Section One", h2_one.text
+    assert_equal 2, h2_one.level
+    assert_equal 1, h2_one.children.size
+
+    h2_two = h1.children.last
+    assert_equal "section-two", h2_two.id
+    assert_equal "Section Two", h2_two.text
+    assert_equal 2, h2_two.level
+    assert_equal 0, h2_two.children.size
+
+    h3 = h2_one.children.first
+    assert_equal "subsection", h3.id
+    assert_equal "Subsection", h3.text
+    assert_equal 3, h3.level
+    assert_equal 0, h3.children.size
+  end
+
+  test "table_of_content returns headings structure for parsed commonmarker markdown" do
+    assert_not_nil @toc_commonmarker.table_of_content
+  end
+
+  test "can limit heading levels" do
+    toc_h1_only = @toc_resource.table_of_content(levels: %w[h1])
+    assert_equal 1, toc_h1_only.size
+    assert_equal 0, toc_h1_only.first.children.size
+
+    toc_h1_h2 = @toc_resource.table_of_content(levels: %w[h1 h2])
+    assert_equal 1, toc_h1_h2.size
+    assert_equal 2, toc_h1_h2.first.children.size
+
+    toc_h1_h2.first.children.each do |h2|
+      assert_equal 0, h2.children.size
+    end
+  end
+
+  test "table_of_contents is an alias for table_of_content" do
+    assert_equal @toc_resource.table_of_content, @toc_resource.table_of_contents
+  end
+
+  test "toc is an alias for table_of_content" do
+    assert_equal @toc_resource.table_of_content, @toc_resource.toc
+  end
+end