docs: add MkDocs site build for the spec#45
Merged
Conversation
Add a documentation site mirroring the openarmature-python stack: MkDocs Material on Cloudflare Pages, with the same theme, palette, plugin set (search, glightbox, llmstxt), and custom CSS copied verbatim. site_url is openarmature.org; deploy project name is openarmature-spec-docs. Content surfaced via symlinks under docs/ so the existing repo structure stays intact: - docs/openarmature.md (charter, in place) - docs/governance.md → ../GOVERNANCE.md - docs/changelog.md → ../CHANGELOG.md - docs/capabilities/<cap>.md → ../../spec/<cap>/spec.md (5 entries) - docs/proposals/<NNNN>-<slug>.md → ../../proposals/<...> (17 entries) A small mkdocs_hooks.py rewrites two cross-reference patterns at build time so links resolve in the rendered site: - ../../proposals/...md → ../proposals/...md (capability pages) - ../GOVERNANCE.md → ../governance.md (proposal pages) Source files are not modified; rewrites happen on in-memory markdown. The workflow builds with --strict on PRs (PR validation only — no deploy) and deploys to Cloudflare Pages on push to main. Cloudflare secrets (CF_API_TOKEN, CF_ACCOUNT_ID) need to be added repo-side before the first deploy succeeds; PR builds work without them. Curated landing page (docs/index.md) mirrors openarmature-python's pattern: hidden-nav landing with a 6-card grid summarizing the four shipped capabilities (graph engine, pipeline utilities, LLM provider, observability), the new prompt-management capability, and the 118-fixture conformance commitment. Conformance fixtures intentionally NOT in nav for v1 — 118 entries would dominate the sidebar. Accessible in the repo, deep-linkable from spec pages.
There was a problem hiding this comment.
Pull request overview
Adds a MkDocs Material documentation site for the OpenArmature spec, mirroring the openarmature-python docs stack. The repo's existing content (capability specs, proposals, GOVERNANCE, CHANGELOG) is surfaced into docs/ via symlinks; a small MkDocs hook rewrites cross-reference paths at build time so links resolve in the rendered site. A GitHub Actions workflow builds with --strict on PRs and deploys to Cloudflare Pages on push to main.
Changes:
- MkDocs Material configuration (
mkdocs.yml,mkdocs_hooks.py,docs/index.md,docs/stylesheets/extra.css) with custom theme/palette, llmstxt + glightbox plugins, and a curated landing page. - Python project metadata for the docs build (
pyproject.tomlwith adocsdependency group and pinneduv.lock). - CI workflow (
.github/workflows/docs.yml) for PR validation and main-branch deploy to Cloudflare Pages;.gitignoreupdates for build artifacts.
Reviewed changes
Copilot reviewed 30 out of 32 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | MkDocs site config (theme, plugins, nav, markdown extensions). |
| mkdocs_hooks.py | Build-time link rewriter for symlinked capability/proposal pages. |
| docs/index.md | Landing page with CTAs and feature-card grid. |
| docs/stylesheets/extra.css | Custom theming (dark + light schemes, layout fixes). |
| pyproject.toml | Minimal project file declaring the docs dependency group. |
| uv.lock | Pinned dependency lockfile for reproducible CI builds. |
| .github/workflows/docs.yml | PR --strict build + main-branch Cloudflare Pages deploy. |
| .gitignore | Ignore site/, .venv/, __pycache__/. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The flat 17-item Proposals section in the sidebar dominated the nav visually. Replace it with a single sidebar entry pointing to a Proposals index page that renders all proposals in a sortable table (number, title, capability, status). Per-proposal pages still resolve at their existing URLs; not_in_nav suppresses the orphan-page warning. Adds tablesort.js (Material's documented integration) for click-to-sort on table column headers.
The right-rail TOC (Material's toc.follow) covers the same need on the docs site, and GitHub's file outline panel covers it on the repo view. Removing the in-page duplicate keeps the file lighter and gets the charter to its first content section faster.
Site polish to ship the docs site to openarmature.org: - Rename ``site_name`` to "OpenArmature Specification" and make the header wordmark a clickable link to the site root (JS shim wraps the title text; CSS keeps it static across all states). Material's default leaves the title as plain text only the small logo icon is clickable. - Restore the left sidebar on the landing so section nav (Charter, Governance, Capabilities, Proposals, Changelog) is discoverable above the fold. - Rewrite the landing for spec-distinct content: hero, use-case cards, "What sets it apart" 2x2 grid, "Why a spec" framing, a prominent reference-implementation admonition for openarmature- python (recolored to OA green), and a closing "How it evolves" paragraph. The original 6-capability grid is dropped — capabilities are one click away in the sidebar. - Footer GitHub icon now links to the LunarCommand org page rather than the spec repo.
Two presentation cleanups for the rendered changelog page on the docs site: - The empty ``[Unreleased]`` heading is removed. The spec workflow tags after every acceptance PR; there is no real Unreleased period to capture. - ``### Added`` / ``### Changed`` / ``### Notes`` / ``### Fixed`` subsections are converted to bold paragraph labels so the right-rail TOC shows only the version+date entries instead of one TOC line per subsection per release.
Five Copilot threads on PR #45 — fixes bundled together per the review skill's one-commit rule. - CHANGELOG.md: softened the "follows Keep a Changelog" header to acknowledge the deviations introduced earlier in this PR (no ``[Unreleased]`` section; bold subsection labels in place of H3). - pyproject.toml + uv.lock: dropped the ``mkdocs-material[imaging]`` extra. The imaging extras pull in Pillow / CairoSVG to support the social plugin's card generation, but no ``social:`` plugin block is configured. Removes ~tens of MB and a Cairo/Pango system dep from CI. - mkdocs_hooks.py: added a docstring author-constraint noting that source files MUST NOT contain the literal substrings the hook rewrites (``](../../proposals/`` or ``](../GOVERNANCE.md``) inside code samples, since the hook uses plain substring replacement. - .github/workflows/docs.yml: added a job-level ``HAS_CF_SECRETS`` env binding and gated the deploy step on it. Protects against a missing or rotated CF secret turning main's status red. - mkdocs.yml + docs/javascripts/tablesort.min.js: vendored Tablesort 5.3.0 under ``docs/javascripts/`` rather than loading from cdnjs. Eliminates the supply-chain risk of a third-party script with no SRI; also fixes a separate bug — the previous cdnjs URL was 404 (cdnjs doesn't host tablesort at that path), so sortable tables would not have worked once deployed. File pulled from jsDelivr, same 5.3.0 release.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
site_urlisopenarmature.org; deploy project name isopenarmature-spec-docs.docs/via symlinks for capability specs (docs/capabilities/<cap>.md → ../../spec/<cap>/spec.md), proposals (docs/proposals/<NNNN>-<slug>.md → ../../proposals/...), GOVERNANCE, and CHANGELOG. The charter (docs/openarmature.md) was already in place.mkdocs_hooks.pyrewrites two cross-reference patterns at build time so links resolve in the rendered site (capability pages:../../proposals/→../proposals/; proposal pages:../GOVERNANCE.md→../governance.md). Source files are not modified.docs/index.md) mirrors python's pattern: hidden-nav landing with two CTAs and a 6-card grid summarizing the five capabilities + the 118-fixture conformance commitment. Conformance fixtures intentionally NOT in nav for v1 (118 entries would dominate the sidebar).--stricton PRs (validation only, no deploy) and deploys to Cloudflare Pages on push to main. Dependency lockfile (uv.lock) committed for reproducible CI builds.Before merge — Cloudflare side (your work)
openarmature-spec-docsPages project on Cloudflare.CF_API_TOKENandCF_ACCOUNT_IDrepo secrets.openarmature.orgDNS at the Pages URL.PR builds will validate the
--strictbuild without secrets. The deploy step fails harmlessly until the secrets exist.Test plan
uv sync --frozen --group docs && uv run mkdocs build --strictbuilds clean (verified once during PR drafting).uv run mkdocs serveopens at http://127.0.0.1:8765/ and renders the landing + nav structure.../../governance/, not../GOVERNANCE/).llms.txtandllms-full.txtare generated undersite/(the latter ~6800 lines, structured by section).--strictvalidation.