add tocs

Gemfile

@@ -1,2 +1,3 @@
 source 'https://rubygems.org'
-gem 'github-pages'
+gem 'github-pages'
+gem 'nokogiri'

Gemfile.lock

@@ -37,6 +37,9 @@ GEM
       rb-inotify (>= 0.9)
       rb-kqueue (>= 0.2)
     maruku (0.7.0)
+    mini_portile (0.5.2)
+    nokogiri (1.6.1-x86-mingw32)
+      mini_portile (~> 0.5.0)
     parslet (1.5.0)
       blankslate (~> 2.0)
     posix-spawn (0.3.8)
@@ -53,10 +56,12 @@ GEM
     safe_yaml (0.9.7)
     toml (0.1.0)
       parslet (~> 1.5.0)
+    yajl-ruby (1.1.0)
     yajl-ruby (1.1.0-x86-mingw32)
 
 PLATFORMS
   x86-mingw32
 
 DEPENDENCIES
   github-pages
+  nokogiri

_includes/top.html

@@ -22,6 +22,8 @@
     <!-- Font Awesome CSS -->
     <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
 
+    <link rel="stylesheet" href="/assets/stylesheets/css/toc.css">
+
     <!-- Latest compiled and minified JavaScript -->
     <script src="/assets/javascript/jquery.min.js"></script>
     <script src="/assets/javascript/bootstrap.min.js"></script>

_layouts/docs.html

@@ -7,7 +7,7 @@
 
         <article class="col-lg-9 col-md-9 col-sm-9">
             <h1>{{ page.title }}</h1>
-            {{ content }}
+            {{ content | toc_generate }}
         </article>
 
         <aside class="col-lg-3 col-md-3 col-sm-3 hidden-xs">

_plugins/tocGenerator.rb

@@ -0,0 +1,117 @@
+require 'nokogiri'
+
+module Jekyll
+  module TOCGenerator
+    TOGGLE_HTML = '<div id="toctitle"><h3>%1</h3>%2</div>'
+    TOC_CONTAINER_HTML = '<div id="toc-container"><table class="toc" id="toc"><tbody><tr><td>%1<ul>%2</ul></td></tr></tbody></table></div>'
+    HIDE_HTML = '<span class="toctoggle">[<a id="toctogglelink" class="internal" href="#">%1</a>]</span>'
+
+   def toc_generate(html)
+        # No Toc can be specified on every single page
+        # For example the index page has no table of contents
+        no_toc = @context.environments.first["page"]["noToc"] || false;
+
+        if no_toc
+            return html
+        end
+
+        config = @context.registers[:site].config
+        # Minimum number of items needed to show TOC, default 0 (0 means no minimum)
+        min_items_to_show_toc = config["minItemsToShowToc"] || 0
+
+        anchor_prefix = config["anchorPrefix"] || 'tocAnchor-'
+
+        # Text labels
+        contents_label = config["contentsLabel"] || 'Contents'
+        hide_label = config["hideLabel"] || 'hide'
+        show_label = config["showLabel"] || 'show'
+        show_toggle_button = config["showToggleButton"]
+
+        toc_html = ''
+        toc_level = 1
+        toc_section = 1
+        item_number = 1
+        level_html = ''
+
+        doc = Nokogiri::HTML(html)
+
+        # Find h3 tag and all its H3 siblings until next h3
+        doc.css('h2').each do |h2|
+            # TODO This XPATH expression can greatly improved
+            ct  = h2.xpath('count(following-sibling::h2)')
+            h3s = h2.xpath("following-sibling::h3[count(following-sibling::h2)=#{ct}]")
+
+            level_html = '';
+            inner_section = 0;
+
+            h3s.map.each do |h3|
+                inner_section += 1;
+                anchor_id = anchor_prefix + toc_level.to_s + '-' + toc_section.to_s + '-' + inner_section.to_s
+                h3['id'] = "#{anchor_id}"
+
+                level_html += create_level_html(anchor_id,
+                    toc_level + 1,
+                    toc_section + inner_section,
+                    item_number.to_s + '.' + inner_section.to_s,
+                    h3.text,
+                    '')
+            end
+            if level_html.length > 0
+                level_html = '<ul>' + level_html + '</ul>';
+            end
+            anchor_id = anchor_prefix + toc_level.to_s + '-' + toc_section.to_s;
+            h2['id'] = "#{anchor_id}"
+
+            toc_html += create_level_html(anchor_id,
+                toc_level,
+                toc_section,
+                item_number,
+                h2.text,
+                level_html);
+
+            toc_section += 1 + inner_section;
+            item_number += 1;
+        end
+
+        # for convenience item_number starts from 1
+        # so we decrement it to obtain the index count
+        toc_index_count = item_number - 1
+
+        if toc_html.length > 0
+            hide_html = '';
+            if (show_toggle_button)
+                hide_html = HIDE_HTML.gsub('%1', hide_label)
+            end
+
+            if min_items_to_show_toc <= toc_index_count
+                replaced_toggle_html = TOGGLE_HTML
+                    .gsub('%1', contents_label)
+                    .gsub('%2', hide_html);
+                toc_table = TOC_CONTAINER_HTML
+                    .gsub('%1', replaced_toggle_html)
+                    .gsub('%2', toc_html);
+                doc.css('body').children.before(toc_table)
+            end
+            doc.css('body').children.to_xhtml(indent:3, indent_text:" ")
+        else
+            return html
+        end
+   end
+
+private
+
+    def create_level_html(anchor_id, toc_level, toc_section, tocNumber, tocText, tocInner)
+        link = '<a href="#%1"><span class="tocnumber">%2</span> <span class="toctext">%3</span></a>%4'
+            .gsub('%1', anchor_id.to_s)
+            .gsub('%2', tocNumber.to_s)
+            .gsub('%3', tocText)
+            .gsub('%4', tocInner ? tocInner : '');
+        '<li class="toc_level-%1 toc_section-%2">%3</li>'
+            .gsub('%1', toc_level.to_s)
+            .gsub('%2', toc_section.to_s)
+            .gsub('%3', link)
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::TOCGenerator)

assets/stylesheets/css/main.css

@@ -6108,6 +6108,29 @@ article h3 {
 article p {
   margin: 20px 0;
 }
+article #toc-container .toc {
+  margin-left: auto;
+  margin-right: auto;
+  background-color: #A09A98;
+  border: none;
+  min-width: 250px;
+}
+article #toc-container .toc td {
+  padding: 15px;
+}
+article #toc-container .toc h3 {
+  border: none;
+  margin-top: 0;
+}
+article #toc-container .toc .tocnumber {
+  padding-right: 5px;
+}
+article #toc-container .toc a {
+  color: #34302d;
+}
+article #toc-container .toc a:hover {
+  border-color: #34302d;
+}
 .highlight,
 p > pre,
 p > code,

assets/stylesheets/css/toc.css

@@ -0,0 +1,40 @@
+
+#toc, .toc, .mw-warning {
+    background-color: #F9F9F9;
+    border: 1px solid #AAAAAA;
+    font-size: 95%;
+    padding: 5px;
+}
+#toc h2, .toc h2 {
+    border: medium none;
+    display: inline;
+    font-size: 100%;
+    font-weight: bold;
+    padding: 0;
+}
+#toc #toctitle, .toc #toctitle, #toc .toctitle, .toc .toctitle {
+    text-align: center;
+}
+#toc ul, .toc ul {
+    list-style-image: none;
+    list-style-type: none;
+    margin-left: 0;
+    margin-bottom: 0;
+    padding-left: 0;
+    text-align: left;
+}
+#toc ul ul, .toc ul ul {
+    margin: 0 0 0 2em;
+}
+#toc .toctoggle, .toc .toctoggle {
+    font-size: 94%;
+}
+
+#toc ul li {
+    list-style-type: none;
+    padding-left: 0;
+}
+
+#toc-container {
+    margin-bottom: 10px;
+}

assets/stylesheets/less/main.less

@@ -216,6 +216,37 @@ article {
   p {
     margin: 20px 0;
   }
+
+  #toc-container {
+    .toc {
+      margin-left: auto;
+      margin-right: auto;
+      background-color: #A09A98;
+      border: none;
+      min-width: 250px;
+
+      td {
+        padding: 15px;
+      }
+
+      h3 {
+        border: none;
+        margin-top: 0;
+      }
+
+      .tocnumber {
+        padding-right: 5px;
+      }
+
+      a {
+        color: @resthub-brown-color;
+
+        &:hover {
+          border-color: @resthub-brown-color;
+        }
+      }
+    }
+  }
 }
 
 .highlight, p > pre, p > code, p > nobr > code, li > code, h5 > code, .note > code {