From d27746ee0b34ef23df483ff63abc8f89eb664f41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Paul=20O=E2=80=99Shannessy?= <paul@oshannessy.com>
Date: Wed, 18 Sep 2013 17:16:29 -0700
Subject: [PATCH] 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                  |  3 +++
 docs/Gemfile.lock             |  6 ++++++
 docs/_plugins/header_links.rb | 17 +++++++++++++++++
 3 files changed, 26 insertions(+)
 create mode 100644 docs/_plugins/header_links.rb

diff --git a/docs/Gemfile b/docs/Gemfile
index 6b98259afb..1eef444e96 100644
--- a/docs/Gemfile
+++ b/docs/Gemfile
@@ -16,3 +16,6 @@ gem 'rb-fsevent'
 
 # Redcarpet for Markdown
 gem 'redcarpet'
+
+# For markdown header cleanup
+gem 'sanitize'
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
index ba45f73fa8..6908961725 100644
--- a/docs/Gemfile.lock
+++ b/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
diff --git a/docs/_plugins/header_links.rb b/docs/_plugins/header_links.rb
new file mode 100644
index 0000000000..9f78b05631
--- /dev/null
+++ b/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
+