Merge pull request #75 from simeonwillbanks/generated-table-of-contents

Generate Table of Contents

Author: jch

README.md

@@ -96,7 +96,7 @@ filter.call
 * `SanitizationFilter` - whitelist sanitize user markup
 * `SyntaxHighlightFilter` - [code syntax highlighter](#syntax-highlighting)
 * `TextileFilter` - convert textile to html
-* `TableOfContentsFilter` - anchor headings with name attributes
+* `TableOfContentsFilter` - anchor headings with name attributes and generate Table of Contents html unordered list linking headings
 
 ## Syntax highlighting
 
@@ -127,7 +127,7 @@ context = {
 # related features.
 SimplePipeline = Pipeline.new [
   SanitizationFilter,
-  TableOfContentsFilter, # add 'name' anchors to all headers
+  TableOfContentsFilter, # add 'name' anchors to all headers and generate toc list
   CamoFilter,
   ImageMaxWidthFilter,
   SyntaxHighlightFilter,

lib/html/pipeline/toc_filter.rb

@@ -1,27 +1,48 @@
 module HTML
   class Pipeline
     # HTML filter that adds a 'name' attribute to all headers
-    # in a document, so they can be accessed from a table of contents
+    # in a document, so they can be accessed from a table of contents.
     #
-    # TODO: besides adding the name attribute, we should get around to
-    # eventually generating the Table of Contents itself, with links
-    # to each header
+    # Generates the Table of Contents, with links to each header.
+    #
+    # Examples
+    #
+    #  TocPipeline =
+    #    HTML::Pipeline.new [
+    #      HTML::Pipeline::TableOfContentsFilter
+    #    ]
+    #  # => #<HTML::Pipeline:0x007fc13c4528d8...>
+    #  orig = %(<h1>Ice cube</h1><p>is not for the pop chart</p>)
+    #  # => "<h1>Ice cube</h1><p>is not for the pop chart</p>"
+    #  result = {}
+    #  # => {}
+    #  TocPipeline.call(orig, {}, result)
+    #  # => {:toc=> ...}
+    #  result[:toc]
+    #  # => "<ul class=\"section-nav\">\n<li><a href=\"#ice-cube\">...</li><ul>"
+    #  result[:output].to_s
+    #  # => "<h1>\n<a name=\"ice-cube\" class=\"anchor\" href=\"#ice-cube\">..."
     class TableOfContentsFilter < Filter
       PUNCTUATION_REGEXP = RUBY_VERSION > "1.9" ? /[^\p{Word}\- ]/u : /[^\w\- ]/
 
       def call
+        result[:toc] = ""
+
         headers = Hash.new(0)
         doc.css('h1, h2, h3, h4, h5, h6').each do |node|
-          name = node.text.downcase
+          text = node.text
+          name = text.downcase
           name.gsub!(PUNCTUATION_REGEXP, '') # remove punctuation
           name.gsub!(' ', '-') # replace spaces with dash
 
           uniq = (headers[name] > 0) ? "-#{headers[name]}" : ''
           headers[name] += 1
           if header_content = node.children.first
+            result[:toc] << %Q{<li><a href="##{name}#{uniq}">#{text}</a></li>\n}
             header_content.add_previous_sibling(%Q{<a name="#{name}#{uniq}" class="anchor" href="##{name}#{uniq}"><span class="octicon octicon-link"></span></a>})
           end
         end
+        result[:toc] = %Q{<ul class="section-nav">\n#{result[:toc]}</ul>} unless result[:toc].empty?
         doc
       end
     end

test/html/pipeline/toc_filter_test.rb

@@ -4,11 +4,27 @@
 class HTML::Pipeline::TableOfContentsFilterTest < Test::Unit::TestCase
   TocFilter = HTML::Pipeline::TableOfContentsFilter
 
+  TocPipeline =
+    HTML::Pipeline.new [
+      HTML::Pipeline::TableOfContentsFilter
+    ]
+
+  def toc
+    result = {}
+    TocPipeline.call(@orig, {}, result)
+    result[:toc]
+  end
+
   def test_anchors_are_added_properly
     orig = %(<h1>Ice cube</h1><p>Will swarm on any motherfucker in a blue uniform</p>)
     assert_includes '<a name=', TocFilter.call(orig).to_s
   end
 
+  def test_toc_list_added_properly
+    @orig = %(<h1>Ice cube</h1><p>Will swarm on any motherfucker in a blue uniform</p>)
+    assert_includes %Q{<ul class="section-nav">\n<li><a href="}, toc
+  end
+
   def test_anchors_have_sane_names
     orig = %(<h1>Dr Dre</h1><h1>Ice Cube</h1><h1>Eazy-E</h1><h1>MC Ren</h1>)
     result = TocFilter.call(orig).to_s
@@ -19,6 +35,14 @@ def test_anchors_have_sane_names
     assert_includes '"mc-ren"', result
   end
 
+  def test_toc_hrefs_have_sane_values
+    @orig = %(<h1>Dr Dre</h1><h1>Ice Cube</h1><h1>Eazy-E</h1><h1>MC Ren</h1>)
+    assert_includes '"#dr-dre"', toc
+    assert_includes '"#ice-cube"', toc
+    assert_includes '"#eazy-e"', toc
+    assert_includes '"#mc-ren"', toc
+  end
+
   def test_dupe_headers_have_unique_trailing_identifiers
     orig = %(<h1>Straight Outta Compton</h1>
              <h2>Dopeman</h2>
@@ -31,6 +55,16 @@ def test_dupe_headers_have_unique_trailing_identifiers
     assert_includes '"dopeman-1"', result
   end
 
+  def test_dupe_headers_have_unique_toc_anchors
+    @orig = %(<h1>Straight Outta Compton</h1>
+              <h2>Dopeman</h2>
+              <h3>Express Yourself</h3>
+              <h1>Dopeman</h1>)
+
+    assert_includes '"#dopeman"', toc
+    assert_includes '"#dopeman-1"', toc
+  end
+
   def test_all_header_tags_are_found_when_adding_anchors
     orig = %(<h1>"Funky President" by James Brown</h1>
              <h2>"It's My Thing" by Marva Whitney</h2>
@@ -41,18 +75,47 @@ def test_all_header_tags_are_found_when_adding_anchors
              <h7>"Be Thankful for What You Got" by William DeVaughn</h7>)
 
     doc = TocFilter.call(orig)
+
     assert_equal 6, doc.search('a').size
   end
 
-  def test_anchors_with_utf8_characters
-    orig = %(<h1>日本語</h1>
-             <h1>Русский</h1)
+  def test_toc_is_complete
+    @orig = %(<h1>"Funky President" by James Brown</h1>
+              <h2>"It's My Thing" by Marva Whitney</h2>
+              <h3>"Boogie Back" by Roy Ayers</h3>
+              <h4>"Feel Good" by Fancy</h4>
+              <h5>"Funky Drummer" by James Brown</h5>
+              <h6>"Ruthless Villain" by Eazy-E</h6>
+              <h7>"Be Thankful for What You Got" by William DeVaughn</h7>)
 
-    rendered_h1s = TocFilter.call(orig).search('h1').map(&:to_s)
+    expected = %Q{<ul class="section-nav">\n<li><a href="#funky-president-by-james-brown">"Funky President" by James Brown</a></li>\n<li><a href="#its-my-thing-by-marva-whitney">"It's My Thing" by Marva Whitney</a></li>\n<li><a href="#boogie-back-by-roy-ayers">"Boogie Back" by Roy Ayers</a></li>\n<li><a href="#feel-good-by-fancy">"Feel Good" by Fancy</a></li>\n<li><a href="#funky-drummer-by-james-brown">"Funky Drummer" by James Brown</a></li>\n<li><a href="#ruthless-villain-by-eazy-e">"Ruthless Villain" by Eazy-E</a></li>\n</ul>}
 
-    assert_equal "<h1>\n<a name=\"%E6%97%A5%E6%9C%AC%E8%AA%9E\" class=\"anchor\" href=\"#%E6%97%A5%E6%9C%AC%E8%AA%9E\"><span class=\"octicon octicon-link\"></span></a>日本語</h1>",
-                 rendered_h1s[0]
-    assert_equal "<h1>\n<a name=\"%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9\" class=\"anchor\" href=\"#%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9\"><span class=\"octicon octicon-link\"></span></a>Русский</h1>",
-                 rendered_h1s[1]
-  end if RUBY_VERSION > "1.9" # not sure how to make this work on 1.8.7
+    assert_equal expected, toc
+  end
+
+  if RUBY_VERSION > "1.9" # not sure how to make this work on 1.8.7
+
+    def test_anchors_with_utf8_characters
+      orig = %(<h1>日本語</h1>
+               <h1>Русский</h1)
+
+      rendered_h1s = TocFilter.call(orig).search('h1').map(&:to_s)
+
+      assert_equal "<h1>\n<a name=\"%E6%97%A5%E6%9C%AC%E8%AA%9E\" class=\"anchor\" href=\"#%E6%97%A5%E6%9C%AC%E8%AA%9E\"><span class=\"octicon octicon-link\"></span></a>日本語</h1>",
+                   rendered_h1s[0]
+      assert_equal "<h1>\n<a name=\"%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9\" class=\"anchor\" href=\"#%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9\"><span class=\"octicon octicon-link\"></span></a>Русский</h1>",
+                   rendered_h1s[1]
+    end
+
+    def test_toc_with_utf8_characters
+      @orig = %(<h1>日本語</h1>
+                <h1>Русский</h1)
+
+      rendered_toc = Nokogiri::HTML::DocumentFragment.parse(toc).to_s
+
+      expected = %Q{<ul class="section-nav">\n<li><a href="#%E6%97%A5%E6%9C%AC%E8%AA%9E">日本語</a></li>\n<li><a href="#%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9">Русский</a></li>\n</ul>}
+
+      assert_equal expected, rendered_toc
+    end
+  end
 end