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:
36
standards/src/hooks.py
Normal file
36
standards/src/hooks.py
Normal 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)
|
||||
@@ -4,6 +4,9 @@ docs_dir: wiki
|
||||
site_dir: ../wiki
|
||||
use_directory_urls: true
|
||||
|
||||
hooks:
|
||||
- hooks.py
|
||||
|
||||
theme:
|
||||
name: material
|
||||
palette:
|
||||
|
||||
Reference in New Issue
Block a user