Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`.
Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs
consumes, so choosing where this lands later costs nothing.
exclude_docs holds back four subtrees, since everything under docs/ would
otherwise be published. archive/ is superseded design and would compete with
the current architecture for a reader's attention; inspiration/ discusses
other products by name; prds/ are open decisions rather than settled design;
github-token.md is credential setup. One PRD is let back through because
architecture/migration-decisions.md links to it three times, and a page
excluded out from under a live link is just a 404 with extra steps.
No nav block. MkDocs derives it from the directory layout, so a new page
under docs/architecture/ publishes without a second edit, and there is no
hand-maintained tree to drift against the repository.
Builds --strict, so a dead internal link fails rather than ships.
The docs site was never published: GitHub Pages is not configured for this
repository, so the workflow built and uploaded a site nobody served. docs/ is
repository documentation — Markdown read in the repository, an editor, or the
forge's file view — and does not need a renderer.
Removed:
- docs/.vitepress/config.mts, docs/package.json, docs/pnpm-lock.yaml (1620
lines), docs/pnpm-workspace.yaml
- docs/index.md (the site's landing page)
- .github/workflows/docs.yml (pnpm install, VitePress build, Pages deploy)
- the docs build-artefact ignores from .gitignore
Kept and corrected:
- docs/prds/01-project-management.md linked its decision documents with
VitePress root-absolute paths (/architecture/...), which only resolve under a
site build. Repointed to repository-relative paths.
- docs/architecture/generated-documentation.md named VitePress as the renderer
throughout. Now records the renderer and publishing surface as an open
decision, with the consequences stated: reference pages unrendered, no link
checker, no authoring server. Also corrected three claims that were never
true — the docsgen all/check subcommands and the docs:* tasks do not exist,
and no pre-commit hook is installed.
- .agents skills: build-and-env and docs-and-writing no longer describe a docs
site to build; the diagnostics scripts drop .vitepress skip rules and the
dead github_docs_build scan.
Generated output is unchanged: docs/data/generated/contracts.json and the
docsgen toolchain are untouched, and tools/ remains its own module.
Fold the old docs/ into the VitePress site and rename docs-2 -> docs.
The 12 architecture PRDs become first-class pages at docs/architecture/
with sidebar nav, rather than being buried under an archive path.
Historical material stays at docs/archive/. Rewrites every docs-2 and
docs/prds/architecture reference across the repo. Site builds clean.