add anchors to headers

Author: davidism

pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
     "gunicorn",
     "lxml",
     "markdown-it-py",
+    "mdit-py-plugins",
     "pygments",
 ]
 

requirements/base.txt

@@ -33,11 +33,15 @@ lxml==5.3.0
     #   feedgen
     #   pallets-web (../pyproject.toml)
 markdown-it-py==3.0.0
-    # via pallets-web (../pyproject.toml)
+    # via
+    #   mdit-py-plugins
+    #   pallets-web (../pyproject.toml)
 markupsafe==2.1.5
     # via
     #   jinja2
     #   werkzeug
+mdit-py-plugins==0.4.2
+    # via pallets-web (../pyproject.toml)
 mdurl==0.1.2
     # via markdown-it-py
 packaging==24.1

requirements/dev.txt

@@ -64,12 +64,16 @@ lxml==5.3.0
     #   -r base.txt
     #   feedgen
 markdown-it-py==3.0.0
-    # via -r base.txt
+    # via
+    #   -r base.txt
+    #   mdit-py-plugins
 markupsafe==2.1.5
     # via
     #   -r base.txt
     #   jinja2
     #   werkzeug
+mdit-py-plugins==0.4.2
+    # via -r base.txt
 mdurl==0.1.2
     # via
     #   -r base.txt

src/pallets/markdown.py

@@ -9,6 +9,7 @@
 from markdown_it.renderer import RendererHTML
 from markdown_it.token import Token
 from markdown_it.utils import OptionsDict
+from mdit_py_plugins.anchors import anchors_plugin
 from pygments.formatters.html import HtmlFormatter
 from pygments.lexers import get_lexer_by_name
 
@@ -110,7 +111,7 @@ def _rewrite_link(
     if ref is None:
         return None
 
-    if ref and ref[0] != "/" and ":" not in ref:
+    if ref and ref[0] not in "/#" and ":" not in ref:
         # rewrite relative links to be served by app views
         if (
             allow_page
@@ -132,6 +133,7 @@ def _rewrite_link(
 
 
 md = MarkdownIt(options_update={"highlight": highlight})
+md.use(anchors_plugin, min_level=2, max_level=6, permalink=True)
 md.add_render_rule("fence", render_fence)
 md.add_render_rule("link_open", render_link_open)
 md.add_render_rule("image", render_image)

src/pallets/static/style.css

@@ -46,3 +46,15 @@ footer ul li {
   white-space: nowrap;
   border: 0;
 }
+
+a.header-anchor {
+  text-decoration: none;
+}
+
+a.header-anchor > p {
+  display: none;
+}
+
+:is(h1, h2, h3, h4, h5, h6):hover > a.header-anchor > p {
+  display: inline
+}