MkDocs retires and the Astro app becomes the only public site, so the artifact is the product and the Markdown stays the source -- the split tools/newsgen already states for releases. tools/docsite walks the published set and writes docs/data/generated/docs.json: every page's directory-style url, title, section and raw Markdown body, plus the sidebar tree derived from the layout. Three things the artifact has to get right, each of which was wrong in a draft: - LINKS. The published pages carry relative .md links that MkDocs rewrote at build time and nothing else will. Each is rewritten to the target page's url using the same function that builds urls, so a link and its target cannot disagree; anchors and scheme-qualified links pass through; assets resolve by the same rule and none are referenced. - FRAGMENTS. A link can resolve to a page and still be broken, because a fragment matching no heading lands the reader at the top of a long document. Each is checked against the target's headings, by the slug rule a table of contents uses. - REFUSAL. A link whose target the set holds back, or whose fragment matches no heading, fails the generator naming the file, the line and the target. This found three citations from settled architecture pointing at two PRDs the blanket prds/* exclusion withheld -- links that were already 404s on the published site, so the exclusion broke citations rather than withholding drafts. Both targets are now published, for a reason distinct from the three ratified PRDs already published. The published set moves out of mkdocs.yml into the generator with its reasons: a renderer reading the artifact cannot see why a page is absent. docs/data/generated is accounted for by docsgen's generatedArtifacts, which now names this file beside contracts.json -- one ownership registry for the directory rather than one per writer, so neither tool reports the other's artifact as unaccounted. docs:artifact regenerates; docs:artifact:check reproduces into memory and fails on drift without touching the tree, wired into task check beside news:check. The existing docs:site target is MkDocs and was left alone -- a first attempt at that name silently ran MkDocs and produced nothing. Verified: task check exit 0, docs:artifact:check reporting 23 pages. The artifact carries 23 pages, no archive/ inspiration/ or news/ entry, and the five PRDs the set declares. Coverage: the published set and its count, url derivation, the nav tree, both refusal paths, and check's no-write guarantee.
63 lines
1.9 KiB
YAML
63 lines
1.9 KiB
YAML
site_name: Archie
|
|
site_description: Event Driven Agentic Automation
|
|
site_url: https://offloaded.dev/docs/
|
|
repo_url: https://github.com/samcharles93/archie-core
|
|
edit_uri: edit/main/docs/
|
|
copyright: Vectis Labs
|
|
|
|
# The published set and the reasons for what is held back now live in
|
|
# tools/docsite/main.go, which emits the canonical artifact a renderer reads
|
|
# (docs/data/generated/docs.json). MkDocs is being retired, so its exclusions are
|
|
# not duplicated here: a second copy of a decision is a second thing to keep true.
|
|
|
|
# The generated release-notes pages are linked from docs/news/index.md and stay
|
|
# published, but they are kept out of the derived navigation: a version list
|
|
# that grows with every release would push the architecture tree off the screen.
|
|
# This is not exclude_docs -- the pages are wanted, just not as nav entries.
|
|
not_in_nav: |
|
|
news/archied/*
|
|
news/archie/*
|
|
|
|
theme:
|
|
name: material
|
|
favicon: public/favicon.svg
|
|
features:
|
|
- navigation.sections
|
|
- navigation.top
|
|
- navigation.instant
|
|
- content.code.copy
|
|
- content.action.edit
|
|
- search.suggest
|
|
- toc.follow
|
|
palette:
|
|
- media: "(prefers-color-scheme: light)"
|
|
scheme: default
|
|
toggle:
|
|
icon: material/weather-night
|
|
name: Dark mode
|
|
- media: "(prefers-color-scheme: dark)"
|
|
scheme: slate
|
|
toggle:
|
|
icon: material/weather-sunny
|
|
name: Light mode
|
|
|
|
markdown_extensions:
|
|
- admonition
|
|
- attr_list
|
|
- tables
|
|
- toc:
|
|
permalink: true
|
|
- pymdownx.details
|
|
- pymdownx.highlight:
|
|
anchor_linenums: true
|
|
- pymdownx.inlinehilite
|
|
- pymdownx.superfences
|
|
|
|
plugins:
|
|
- search
|
|
|
|
# No nav block on purpose. MkDocs derives the tree from the directory layout, so
|
|
# adding a page under docs/architecture/ publishes it without a second edit here.
|
|
# A hand-maintained nav is one more thing that goes stale against 600 commits a
|
|
# month.
|