docs(standards): rebase cross-kind wiki links via MkDocs hook

The standards wiki links to the sibling library reference with ../lib/... paths. Add src/hooks.py and enable it in mkdocs.wiki.yml so those links climb to the repo root and resolve to /standards/lib/... under directory URLs.
This commit is contained in:
2026-10-17 17:22:37 +05:30
parent f2f09cf2c9
commit a1b74e5086
7 changed files with 48 additions and 9 deletions

36
standards/src/hooks.py Normal file
View File

@@ -0,0 +1,36 @@
"""MkDocs hook: rebase cross-kind links to the repository root.
The standards wiki links to the sibling library reference with
source-relative paths such as ``../lib/13_library_registry/``. MkDocs only
rewrites links whose target lives inside ``docs_dir``, so those links are
emitted verbatim and, under ``use_directory_urls``, resolve into
``/standards/wiki/lib/...`` and break.
This hook rewrites ``../lib/``, ``../api/`` and ``../wiki/`` links to climb to
the repository root, so they resolve to ``/<repo>/<kind>/`` regardless of how
deeply the page is nested. It mirrors the ``docforge-linkfix`` MkDocs plugin.
"""
from __future__ import annotations
import re
_CROSS_KIND_LINK = re.compile(r"\]\((?:\.\./)+(lib|api|wiki)/")
def on_page_markdown(markdown, *, page, config, files):
"""Prefix cross-kind links with the depth required to reach the repo root.
Args:
markdown (str): The raw Markdown source of the current page.
page: The page being rendered; its destination URI determines how many
directory levels the output sits below the site root.
config: The active MkDocs configuration (unused).
files: The collection of files in the site (unused).
Returns:
str: The Markdown with cross-kind links rebased to the repo root.
"""
depth = page.file.dest_uri.count("/")
prefix = "../" * (depth + 1)
return _CROSS_KIND_LINK.sub(lambda match: f"]({prefix}{match.group(1)}/", markdown)

View File

@@ -4,6 +4,9 @@ docs_dir: wiki
site_dir: ../wiki
use_directory_urls: true
hooks:
- hooks.py
theme:
name: material
palette: