Fix #2636

CHANGES.txt

@@ -13,6 +13,7 @@ Math support changes
 Features
 --------
 
+* New `add_header_permalinks` filter, for Sphinx-style header links (Issue #2636)
 * Add a list of template variables to documentation (Issues #2328,
   #2712, #2259) and update the theming reference (Issue #2259)
 * Add ``{post_title}`` tag for Read More links (Issue #2709)

docs/manual.txt

@@ -1904,6 +1904,13 @@ jsonminify
 xmlminify
    Minify XML files. Suitable for Nikola’s sitemaps and Atom feeds.
 
+add_header_permalinks
+   Add links next to every header, Sphinx-style. You will need to add styling for the `headerlink` class,
+   in `custom.css`, for example::
+
+        .headerlink { opacity: 0.1 }
+        .headerlink:hover { opacity: 1; text-decoration: none; }
+
 You can apply filters to specific posts or pages by using the ``filters`` metadata field:
 
 .. code:: restructuredtext

nikola/filters.py

@@ -33,6 +33,7 @@
 import shutil
 import subprocess
 import tempfile
+import uuid
 import shlex
 
 import lxml
@@ -391,3 +392,14 @@ def _normalize_html(data):
 
 
 normalize_html = apply_to_text_file(_normalize_html)
+
+
+@apply_to_text_file
+def add_header_permalinks(data):
+    doc = lxml.html.document_fromstring(data)
+    for h in ['h1', 'h2', 'h3', 'h4']:
+        nodes = doc.findall('*//%s' % h)
+        for node in nodes:
+            new_node = lxml.html.fragment_fromstring('<a id="{0}" href="#{0}" class="headerlink" title="Permalink to this headline">&nbsp;&pi;</a>'.format(uuid.uuid4()))
+            node.append(new_node)
+    return lxml.html.tostring(doc, encoding="unicode")