diff --git a/lib/rocco/layout.mustache b/lib/rocco/layout.mustache
index c611875..f76bb0e 100644
--- a/lib/rocco/layout.mustache
+++ b/lib/rocco/layout.mustache
@@ -29,10 +29,10 @@
   </thead>
   <tbody>
     {{#sections}}
-    <tr id='section-{{ num }}'>
+    <tr id='section-{{ section_id }}'>
       <td class=docs>
         <div class="pilwrap">
-          <a class="pilcrow" href="#section-{{ num }}">&#182;</a>
+          <a class="pilcrow" href="#section-{{ section_id }}">&#182;</a>
         </div>
         {{{ docs }}}
       </td>
diff --git a/lib/rocco/layout.rb b/lib/rocco/layout.rb
index a2a59c4..25bfd7e 100644
--- a/lib/rocco/layout.rb
+++ b/lib/rocco/layout.rb
@@ -18,16 +18,19 @@ class Rocco::Layout < Mustache
   def sections
     num = 0
     @doc.sections.map do |docs,code|
+      is_header = /^<h.>(.+)<\/h.>$/.match( docs )
+      header_text = is_header && is_header[1].split.join("_")
+      num += 1
       {
         :docs       =>  docs,
         :docs?      =>  !docs.empty?,
-        :header?    =>  /^<h.>.+<\/h.>$/.match( docs ),
+        :header?    =>  is_header,
 
         :code       =>  code,
         :code?      =>  !code.empty?,
 
         :empty?     =>  ( code.empty? && docs.empty? ),
-        :num        =>  (num += 1)
+        :section_id =>  is_header ? header_text : num
       }
     end
   end
diff --git a/test/test_descriptive_section_names.rb b/test/test_descriptive_section_names.rb
new file mode 100644
index 0000000..21c42ce
--- /dev/null
+++ b/test/test_descriptive_section_names.rb
@@ -0,0 +1,29 @@
+require File.dirname(__FILE__) + '/helper'
+
+class RoccoDescriptiveSectionNamesTests < Test::Unit::TestCase
+  def test_section_name
+    r = roccoize( "filename.rb", "# # Comment 1\ndef codeblock\nend\n" )
+    html = r.to_html
+    assert(
+      html.include?( "<tr id='section-Comment_1'>" ),
+      "The first section should be named"
+    )
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-Comment_1">' ),
+      "The rendered HTML should link to a named section"
+    )
+  end
+  def test_section_numbering
+    r = roccoize( "filename.rb", "# # Header 1\ndef codeblock\nend\n# Comment 1\ndef codeblock1\nend\n# # Header 2\ndef codeblock2\nend" )
+    html = r.to_html
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-Header_1">' ) &&
+      html.include?( '<a class="pilcrow" href="#section-Header_2">' ),
+      "First and second headers should be named sections"
+    )
+    assert(
+      html.include?( '<a class="pilcrow" href="#section-2">' ),
+      "Sections should continue numbering as though headers were counted."
+    )
+  end
+end