Docs: Give headers ids for easy linking

This gives markdown headers an id so that we can link directly to
sections of our docs. This is better than the alternative of adding them
all ourselves.

docs/Gemfile

@@ -16,3 +16,6 @@ gem 'rb-fsevent'
 
 # Redcarpet for Markdown
 gem 'redcarpet'
+
+# For markdown header cleanup
+gem 'sanitize'

docs/Gemfile.lock

@@ -24,6 +24,9 @@ GEM
     liquid (2.5.0)
     maruku (0.6.1)
       syntax (>= 1.0.0)
+    mini_portile (0.5.1)
+    nokogiri (1.6.0)
+      mini_portile (~> 0.5.0)
     posix-spawn (0.3.6)
     pygments.rb (0.5.0)
       posix-spawn (~> 0.3.6)
@@ -32,6 +35,8 @@ GEM
     rb-fsevent (0.9.3)
     redcarpet (2.2.2)
     safe_yaml (0.7.1)
+    sanitize (2.0.6)
+      nokogiri (>= 1.4.4)
     sass (3.2.9)
     syntax (1.0.0)
     yajl-ruby (1.1.0)
@@ -45,4 +50,5 @@ DEPENDENCIES
   rake
   rb-fsevent
   redcarpet
+  sanitize
   sass

docs/_plugins/header_links.rb

@@ -0,0 +1,17 @@
+require 'redcarpet'
+require 'sanitize'
+
+# Simple converter that is probably better than RedCarpet's built in TOC id
+# generator (which ends up with things lik id="toc_1"... terrible).
+
+class Redcarpet::Render::HTML
+  def header(title, level)
+    clean_title = Sanitize.clean(title)
+      .downcase
+      .gsub(/\s+/, "-")
+      .gsub(/[^A-Za-z0-9\-_.]/, "")
+
+    return "<h#{level} id=\"#{clean_title}\">#{title}</h#{level}>"
+  end
+end
+