- Add optional in-document Table of Contents

Author: DannyBen

Gemfile

@@ -9,6 +9,7 @@ group :development do
   # gem 'github-pages', group: :jekyll_plugins
 
   gem 'byebug'
+  gem 'lp'
   gem 'rack-test'
   gem 'rdoc'
   gem 'rspec'

lib/madness.rb

@@ -1,4 +1,7 @@
-require 'byebug' if ENV['BYEBUG']
+if ENV['BYEBUG']
+  require 'byebug'
+  require 'lp'
+end
 
 require 'requires'
 

lib/madness/document.rb

@@ -99,6 +99,7 @@ def markdown
     def markdown_to_html
       doc = CommonMarker.render_doc markdown, :DEFAULT, [:table]
 
+      replace_toc_marker doc
       add_anchor_ids doc
       html = doc.to_html :UNSAFE
       html = syntax_highlight(html) if config.highlighter
@@ -121,6 +122,34 @@ def add_anchor_ids(doc)
       end
     end
 
+    # Replace <!-- TOC --> with a Table of Contents for the page
+    def replace_toc_marker(doc)
+      toc_marker = doc.find do |node|
+        node.type == :html and node.string_content.include? "<!-- TOC -->"
+      end
+
+      return unless toc_marker
+
+      toc = []
+      doc.walk do |node|
+        next unless node.type == :header
+        level = node.header_level
+        next unless level.between? 2, 3
+        text = node.first_child.string_content
+
+        if level == 2
+          toc << "- [#{text}](##{text.to_slug})"
+        else
+          toc << "  - [#{text}](##{text.to_slug})"
+        end    
+      end
+
+      toc = toc.join "\n"
+      toc = CommonMarker.render_doc toc
+      toc_marker.insert_after toc.first_child
+      toc_marker.insert_after CommonMarker.render_doc("## Table of Contents").first_child
+    end
+
     # If the document does not start with an H1 tag, add it.
     def prepend_h1(html)
       unless html[0..3] == "<h1>"

madness.gemspec

@@ -25,13 +25,11 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'json', '~> 2.1'
   s.add_runtime_dependency 'naturally', '~> 2.2'
   s.add_runtime_dependency 'os', '~> 1.0'
-  s.add_runtime_dependency 'puma', '~> 5.0'
-  # s.add_runtime_dependency 'rack-contrib', '~> 2.1'
+  s.add_runtime_dependency 'puma', '~> 4.0'
   s.add_runtime_dependency 'rack-ssl', '~> 1.4'
   s.add_runtime_dependency 'requires', '~> 0.1'
   s.add_runtime_dependency 'sass', '~> 3.7'
   s.add_runtime_dependency 'sinatra', '~> 2.0', '>= 2.0.5'
-  # s.add_runtime_dependency 'sinatra-contrib', '~> 2.0', '>= 2.0.5'
   s.add_runtime_dependency 'slim', '~> 4.0'
   s.add_runtime_dependency 'extended_yaml', '~> 0.2'
   s.add_runtime_dependency 'addressable', '~> 2.7'

out.html

@@ -0,0 +1,19 @@
+## Table of Contents
+
+- [Purpose](#purpose)
+- [Scope](#scope)
+- [Background](#background)
+- [Exceptions](#exceptions)
+- [Policy](#policy)
+  - [Phase 1: Preliminary analysis](#phase-1-preliminary-analysis)
+  - [Phase 2: Systems analysis and requirements definition](#phase-2-systems-analysis-and-requirements-definition)
+  - [Phase 3: Systems design](#phase-3-systems-design)
+  - [Phase 4: Development](#phase-4-development)
+  - [Phase 5: Integration and testing](#phase-5-integration-and-testing)
+  - [Phase 6: Acceptance and deployment](#phase-6-acceptance-and-deployment)
+  - [Phase 7: Maintenance plan](#phase-7-maintenance-plan)
+- [Appendix A - Security aspects](#appendix-a---security-aspects)
+- [Appendix B - Dependency upgrade guidelines](#appendix-b---dependency-upgrade-guidelines)
+  - [Upgrading vulnerable dependencies](#upgrading-vulnerable-dependencies)
+  - [Upgrading high-impact dependencies](#upgrading-high-impact-dependencies)
+  - [Upgrading low-impact dependencies](#upgrading-low-impact-dependencies)

spec/fixtures/docroot/File with TOC.md

@@ -0,0 +1,19 @@
+# File with TOC
+
+<!-- TOC -->
+
+## Subject 1
+
+Some text
+
+### Subject 1.1
+
+Some text
+
+### Subject 1.2
+
+Some text
+
+## Subject 2
+
+Some text

spec/fixtures/document-toc

@@ -0,0 +1,20 @@
+<h1><a id='file-with-toc'></a>File with TOC</h1>
+<!-- TOC -->
+<h2><a id='table-of-contents'></a>Table of Contents</h2>
+<ul>
+<li><a href="#subject-1">Subject 1</a>
+<ul>
+<li><a href="#subject-11">Subject 1.1</a></li>
+<li><a href="#subject-12">Subject 1.2</a></li>
+</ul>
+</li>
+<li><a href="#subject-2">Subject 2</a></li>
+</ul>
+<h2><a id='subject-1'></a>Subject 1</h2>
+<p>Some text</p>
+<h3><a id='subject-11'></a>Subject 1.1</h3>
+<p>Some text</p>
+<h3><a id='subject-12'></a>Subject 1.2</h3>
+<p>Some text</p>
+<h2><a id='subject-2'></a>Subject 2</h2>
+<p>Some text</p>

spec/fixtures/toc

@@ -28,4 +28,5 @@
 1. [File](/File)
 1. [File-with-Dashes](/File-with-Dashes)
 1. [File with Spaces](/File%20with%20Spaces)
+1. [File with TOC](/File%20with%20TOC)
 1. [File without H1](/File%20without%20H1)

spec/madness/document_spec.rb

@@ -248,6 +248,11 @@
       expect(doc.content).to have_tag :a, id: 'just-a-file'
     end
 
+    it "replaces <!-- TOC --> markers with table of contents" do
+      doc = described_class.new "File with TOC"
+      expect(doc.content).to match_approval 'document-toc'
+    end
+
     context "when headers contain links" do
       subject { described_class.new "CHANGELOG" }