From 9e11fb626e04adcd3bf4c845e96465021a3ba757 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 ecb91bd588..71938cf7e4 100644
--- a/docs/Gemfile
+++ b/docs/Gemfile
@@ -14,3 +14,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 c83002c537..5a22bb6f41 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)
@@ -31,6 +34,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)
@@ -43,4 +48,5 @@ DEPENDENCIES
   json
   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
+