Add header_links feature

lib/kramdown/converter/html.rb

@@ -151,6 +151,13 @@ def convert_header(el, indent)
         if @options[:auto_ids] && !attr['id']
           attr['id'] = generate_id(el.options[:raw_text])
         end
+
+        if @options[:header_links] && attr['id'].to_s.length > 0
+          link = Element.new(:a, nil, nil)
+          link.attr['href'] = "##{attr['id']}"
+          el.children.unshift(link)
+        end
+
         @toc << [el.options[:level], attr['id'], el.children] if attr['id'] && in_toc?(el)
         level = output_header_level(el.options[:level])
         format_as_block_html("h#{level}", attr, inner(el, indent), indent)

lib/kramdown/options.rb

@@ -236,6 +236,15 @@ def self.simple_hash_validator(val, name)
       Used by: HTML/Latex converter
     EOF
 
+    define(:header_links, Boolean, false, <<~EOF)
+      Adds anchor tags within headers that can be used to generate permalinks
+      when not using a table of contents.
+
+      The anchor tags are empty, but can be styled to your liking.
+
+      Default: false
+    EOF
+
     define(:transliterated_header_ids, Boolean, false, <<~EOF)
       Transliterate the header text before generating the ID
 

test/test_files.rb

@@ -266,6 +266,7 @@ def tidy_output(out)
 
   EXCLUDE_MODIFY = [
     'test/testcases/block/06_codeblock/rouge/multiple.text', # bc of HTMLFormater in options
+    'test/testcases/block/04_header/with_header_links.text', # we add an anchor tag
   ].compact
 
   # Generate test methods for asserting that converters don't modify the document tree.

test/testcases/block/04_header/with_header_links.html

@@ -0,0 +1,9 @@
+<h1 id="this-is-a-header"><a href="#this-is-a-header"></a>This is a header</h1>
+
+<h2 id="another-one-1-here"><a href="#another-one-1-here"></a>12. Another one-1-here</h2>
+
+<h3 id="do--it-now"><a href="#do--it-now"></a>Do ^&amp; it now</h3>
+
+<h1 id="header-with-childrenhttpexamplecom"><a href="#header-with-childrenhttpexamplecom"></a>Header <em>with <a href="http://example.com">children</a></em></h1>
+
+<h1>Header without ID</h1>

test/testcases/block/04_header/with_header_links.options

@@ -0,0 +1 @@
+:header_links: true

test/testcases/block/04_header/with_header_links.text

@@ -0,0 +1,10 @@
+# This is a header
+
+## 12. Another one-1-here
+
+### Do ^& it now
+
+# Header *with [children](http://example.com)*
+
+# Header without ID
+{: id=""}