diff --git a/standards/lib/sitemap.xml.gz b/standards/lib/sitemap.xml.gz index 0ddb2ac..2bca4d8 100644 Binary files a/standards/lib/sitemap.xml.gz and b/standards/lib/sitemap.xml.gz differ diff --git a/standards/src/hooks.py b/standards/src/hooks.py new file mode 100644 index 0000000..ccd4131 --- /dev/null +++ b/standards/src/hooks.py @@ -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 ``///`` 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 0ddb2ac..2bca4d8 100644 Binary files a/standards/wiki/sitemap.xml.gz and b/standards/wiki/sitemap.xml.gz differ