docs site: rewrite directory-style links to their landing pages

A MkDocs hook turns links like [incidents/](incidents/) — which Gitea
renders as a directory listing but a static site would resolve against the
page URL — into links to the generated landing page for that directory.

mkdocs.yml

@@ -87,6 +87,11 @@ plugins:
   # Built-in, offline search — the index is a JSON file in the build output.
   - search
 
+hooks:
+  # Rewrites directory-style links (e.g. [incidents/](incidents/)) to the
+  # landing pages the build generates for them. Publishing-layer logic only.
+  - publishing/hooks.py
+
 markdown_extensions:
   - admonition
   - attr_list

publishing/build.sh

@@ -34,6 +34,7 @@ tar cf - \
   --exclude='.site-build' \
   --exclude='.venv-docs' \
   --exclude='*.sh' \
+  --exclude='*.py' \
   --exclude='publishing/webhook-receiver.py' \
   --exclude='publishing/webhook-receiver.service' \
   --exclude='mkdocs.yml' \

publishing/hooks.py

@@ -0,0 +1,38 @@
+"""MkDocs hook: make directory-style links work on a static site.
+
+The documents sometimes link to a directory the way Gitea renders it, e.g.
+infrastructure.md contains [`incidents/`](incidents/). On a static site with
+directory URLs, that href resolves relative to the *page* (giving
+/infrastructure/incidents/ and a 404). This hook rewrites such links to the
+generated landing page for that directory (build.sh creates
+<dir>/index.md for documented directories that lack one). It never edits the
+documents themselves.
+"""
+
+import posixpath
+import re
+
+from mkdocs.utils import get_relative_url
+
+_HREF = re.compile(r'(href=)("([^"]+)/")')
+
+
+def on_page_content(html, page, config, files):
+    index_urls = {}
+    for f in files:
+        src = f.src_path
+        if src.endswith("/index.md"):
+            index_urls[posixpath.dirname(src)] = f.url
+
+    page_dir = posixpath.dirname(page.file.src_path)
+
+    def fix(match):
+        href = match.group(3)
+        if href.startswith(("http://", "https://", "/", "#")):
+            return match.group(0)
+        target = posixpath.normpath(posixpath.join(page_dir, href))
+        if target in (".", "..") or target not in index_urls:
+            return match.group(0)
+        return f'{match.group(1)}"{get_relative_url(index_urls[target], page.file.url)}"'
+
+    return _HREF.sub(fix, html)