From a1b74e5086545108f21751a386e616d5e2a90601 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 17 Oct 2026 17:22:37 +0530 Subject: [PATCH] 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. --- standards/lib/sitemap.xml.gz | Bin 127 -> 127 bytes standards/src/hooks.py | 36 ++++++++++++++++++ standards/src/mkdocs.wiki.yml | 3 ++ standards/wiki/01_overview/index.html | 2 +- standards/wiki/03_start_an_app/index.html | 10 ++--- .../04_development/02_releasing/index.html | 6 +-- standards/wiki/sitemap.xml.gz | Bin 127 -> 127 bytes 7 files changed, 48 insertions(+), 9 deletions(-) create mode 100644 standards/src/hooks.py diff --git a/standards/lib/sitemap.xml.gz b/standards/lib/sitemap.xml.gz index 0ddb2ac7fd534af7db9a09cf46d47afef404ba56..2bca4d8cc9f08181cf8765ebf86e6fc7624667ea 100644 GIT binary patch delta 13 Ucmb=gXP58h;Aq%&X(D?C03US(+yDRo delta 13 Ucmb=gXP58h;9$tSIFY>q02//`` 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) diff --git a/standards/src/mkdocs.wiki.yml b/standards/src/mkdocs.wiki.yml index 7ccab5e..6ca22eb 100644 --- a/standards/src/mkdocs.wiki.yml +++ b/standards/src/mkdocs.wiki.yml @@ -4,6 +4,9 @@ docs_dir: wiki site_dir: ../wiki use_directory_urls: true +hooks: + - hooks.py + theme: name: material palette: diff --git a/standards/wiki/01_overview/index.html b/standards/wiki/01_overview/index.html index 504f705..3d4f40a 100644 --- a/standards/wiki/01_overview/index.html +++ b/standards/wiki/01_overview/index.html @@ -671,7 +671,7 @@ port/adapter binding, performed by the composition root at startup.

  • Spec-first. The HTTP contract is declared in openapi.yaml; route handlers are looked up by operationId. There are no decorator routers.
  • Reuse the libraries. Orchestration, DI, Mongo repositories, ingestion, - auth, and docs come from internal libraries โ€” see the Library + auth, and docs come from internal libraries โ€” see the Library Registry.
  • Explicit state machines. Long-running work moves through explicit, durable statuses and can pause for human input.
    • diff --git a/standards/wiki/03_start_an_app/index.html b/standards/wiki/03_start_an_app/index.html index db557c4..a006807 100644 --- a/standards/wiki/03_start_an_app/index.html +++ b/standards/wiki/03_start_an_app/index.html @@ -579,7 +579,7 @@ copying Tier B template components.

    Doc model: this page is the human entry point. The deterministic, machine-facing checklist lives in the reference page -Build Recipe, served as docs://modules/build_recipe.

    +Build Recipe, served as docs://modules/build_recipe.

    ๐Ÿงพ What the agent needs from you

    @@ -592,7 +592,7 @@ machine-facing checklist lives in the reference page the families and their input formats (or "none").
  • Auth needed now? Default no. Auth is deferred (py-jwt primitives only), and an authless app is just a spec with no security keys โ€” see - Spec-First Routing โ†’ Authless apps.
    • + Spec-First Routing โ†’ Authless apps.
  • Integrations. Mongo, ingestion formats, email, LLM provider.

    • If you can state axes 1 and 2, the rest is mechanical.

    @@ -619,9 +619,9 @@ machine-facing checklist lives in the reference page

    ๐Ÿ“š Reference

    diff --git a/standards/wiki/04_development/02_releasing/index.html b/standards/wiki/04_development/02_releasing/index.html index e0bab80..1f80f23 100644 --- a/standards/wiki/04_development/02_releasing/index.html +++ b/standards/wiki/04_development/02_releasing/index.html @@ -622,10 +622,10 @@

    Releasing & Versioning

    How to cut a release of any Aetos repository. The rule lives in the reference -page Versioning & Changelog; this is the +page Versioning & Changelog; this is the runbook you follow.

    Every repository is one of two Drone shapes โ€” a PyPI package or a Docker -deployment (Drone Pipelines). Both release the +deployment (Drone Pipelines). Both release the same way: the version bump and changelog promotion go in the merge request, and the tag is created on the merged commit.

    @@ -750,7 +750,7 @@ outage):

    diff --git a/standards/wiki/sitemap.xml.gz b/standards/wiki/sitemap.xml.gz index 0ddb2ac7fd534af7db9a09cf46d47afef404ba56..2bca4d8cc9f08181cf8765ebf86e6fc7624667ea 100644 GIT binary patch delta 13 Ucmb=gXP58h;Aq%&X(D?C03US(+yDRo delta 13 Ucmb=gXP58h;9$tSIFY>q02