Display a table of contents in the sidebar of man pages

Adds the table of contents to the frontmatter of the generated HTML
pages, then renders it in the Hugo template.

Author: jvns

layouts/partials/sidebar.html

@@ -49,6 +49,20 @@
         <a href="{{ relURL "community" }}"{{ if (eq $section "community") }} class="active"{{ end }}>Community</a>
       </li>
     </ul>
+
+    {{ $headings := .Params.headings }}
+    {{ if $headings }}
+    <ul>
+      <li> Table of Contents
+        <ul class="expanded">
+          {{ range $i, $item := $headings }}
+            <li><a href="#{{ .id }}">{{ .text }}</a> </li>
+          {{ end }}
+        </ul>
+      </li>
+    </ul>
+    {{ end }}
+
     {{ if (eq .Params.Sidebar "book") }}
       <hr class="sidebar">
       {{- /* If this page displays a section of the ProGit book, map all the translations thereof */ -}}

script/update-docs.rb

@@ -81,6 +81,20 @@ def expand_l10n(path, content, get_f_content, categories, ext)
   content
 end
 
+def extract_headings(html)
+  doc = Nokogiri::HTML::DocumentFragment.parse(html)
+  headings = []
+
+  doc.css('h2').each do |heading|
+    headings << {
+      'text' => heading.text.strip,
+      'id' => heading['id']
+    }
+  end
+
+  headings
+end
+
 def index_l10n_doc(filter_tags, doc_list, get_content)
   rebuild = ENV.fetch("REBUILD_DOC", nil)
   rerun = ENV["RERUN"] || rebuild || false
@@ -220,6 +234,11 @@ def index_l10n_doc(filter_tags, doc_list, get_content)
         "aliases" => ["/docs/#{path}/#{lang}/index.html"]
       }
 
+      headings = extract_headings(html)
+      if headings.length > 0
+        front_matter['headings'] = headings
+      end
+
       FileUtils.mkdir_p(doc_path)
       File.open("#{doc_path}/#{lang}.html", "w") do |out|
         out.write(wrap_front_matter(front_matter))
@@ -525,6 +544,11 @@ def index_doc(filter_tags, doc_list, get_content)
           "version" => doc_versions[changed_in],
         }
 
+        headings = extract_headings(html)
+        if headings.length > 0
+          front_matter['headings'] = headings
+        end
+
         if changed_in != doc_version_index && File.exist?("#{doc_path}/#{version}.html")
           # remove obsolete file
           File.delete("#{doc_path}/#{version}.html")
@@ -736,3 +760,4 @@ def local_index_doc(index_fun)
 else
   abort("Need two arguments: (<path-to-repo> | remote) (en | l10n)!")
 end
+