Documentation website¶
The SummonOS wiki renders the repository's existing Markdown with MkDocs and Material for MkDocs. The Markdown files remain canonical: edit them in their current repository paths, not in generated output. The website adds grouped navigation, full-text search, an on-page table of contents, mobile navigation, light/dark modes, code highlighting and copying, and GitHub source/edit links.
The site describes several different kinds of evidence. Start with project status for the difference between current checkout behavior, numbered releases, and remaining acceptance gates. Plans, research, and UX-surface reports appear under Historical archive, with a site-only notice; publication does not turn a dated proposal or old test result into a current product guarantee.
Local setup¶
Use Python 3.12 (the CI version), pip, and a virtual environment. Documentation dependencies are separate
from the Swift packages; they are not linked into Summon, macctl, or generated apps. No Node tooling,
bespoke JavaScript, or frontend framework is required.
From the repository root:
python3 -m venv "${TMPDIR:-/tmp}/summonos-docs-venv"
. "${TMPDIR:-/tmp}/summonos-docs-venv/bin/activate"
python -m pip install -r requirements-docs.txt
The directly selected MkDocs, Material, Markdown-extension, and YAML versions are pinned in
requirements-docs.txt. Update those pins deliberately and run a complete
strict build and browser review together; a dependency upgrade is not an application-runtime dependency
change.
Preview and strict build¶
Open http://127.0.0.1:8000/. Preview uses the same root path as the custom Vercel domain. The server watches canonical documents and refreshes the staging tree and discovered navigation on rebuild. Stop it with Control-C. To choose another address:
Build the complete public site, including the archive:
Both commands use MkDocs strict mode. The build also validates rendered HTML links, images, and local fragments, including raw HTML that MkDocs' Markdown link validation does not cover. A missing source file, local route, image, or heading is an error, not silently redirected to the homepage. External GitHub and third-party URLs are not network-checked by this build.
The focused, standard-library link regressions also run in CI:
They cover relocated links, escaped backticks, literal examples, raw HTML/reference links and rejected missing/outside targets. Local preview watches canonical sources, not its own generated staging tree.
The default build output is outside the checkout:
- macOS:
$HOME/Library/Caches/SummonOS/docs/site - Other platforms:
$HOME/.cache/SummonOS/docs/site
The temporary staged Markdown and generated MkDocs configuration are removed when the command exits. The HTML build remains in the output directory until replaced or removed. An explicit output path must also be outside the repository:
Run the wrapper, not a bare mkdocs build: the wrapper supplies the multi-directory source mapping,
archive notices, discovered navigation, and correct GitHub edit destinations. Do not copy documents into
docs/ just to make them visible to MkDocs.
For branch review, make source-only and edit links point at that branch or an exact revision:
This changes link destinations, not which checkout is built. Without --ref, links target main.
Public source mapping¶
tools/docs-site.py discovers the following sources automatically on each build.
Every selected Markdown document is included in navigation and search, not just documents already linked
from a hand-maintained landing page.
| Canonical source | Site location or grouping |
|---|---|
docs/home.md |
Site homepage (index.md in temporary staging) |
Root README.md |
Get started → About SummonOS (overview.md in staging) |
Root CONTRIBUTING.md, SECURITY.md, plugins.md |
Build apps, Knowledge base, and Use SummonOS |
docs/**/*.md |
User guides, feature/security references, architecture decisions, catalog, and historical archive |
incubator/summon/README.md, CHANGELOG.md, THIRD_PARTY_NOTICES.md |
Use SummonOS → Summon |
incubator/summon/docs/**/*.md |
Use SummonOS → Summon, including its interface specifications and audits |
macctl/README.md, macctl/docs/**/*.md |
Use SummonOS → macctl and its settings reference |
incubator/summon/templates/*/README.md |
Build apps → Templates |
| Public images and PDF assets referenced by selected pages; public images/PDF/text/CSS assets under selected docs trees | Copied into temporary staging with their repository-relative paths |
All selected README.md filenames become overview.md in staging. This avoids MkDocs' special handling
of README.md as an index, especially in directories that already have a generated index.md.
Other filenames and directory layouts are preserved, apart from the homepage relocation. The wrapper
rewrites links using the original document's directory, so source-relative links work on GitHub and
on the site, including links from the relocated homepage. HTML href, src, and srcset attributes are
mapped to the final output location too. Fenced examples and inline code are left as examples.
Task files, AGENTS.md, PROJECT-CONTEXT.md, hidden directories, and vendored skills are not staged or
search-indexed. Links to existing repository-only targets, such as a Swift file, shell script, agent rule,
license, or source directory, become explicit GitHub blob or tree URLs at the selected ref. They do
not create pretend website routes. Missing source targets still fail the build; do not hide a genuine
broken link by widening the public allowlist. Linked symlinks are refused rather than following files
outside the public tree.
Maintaining documentation¶
- Edit canonical Markdown and keep its existing source-relative links. Use Markdown links to
.mddocuments, not generated HTML paths. Link to a real heading when adding a fragment. - New
docs/concepts need OKF frontmatter:type,title,description, andtags. Plans retain historicalcreatedandstatusfields and distinguish later amendments from the original proposal. - Regenerate the knowledge-catalog indexes with
python tools/okf-index.py; do not hand-edit them. These indexes remain useful when reading the repository without the website. - Add a notable documentation change to the update log. Update features only when implemented user-visible behavior changes, not when a plan merely proposes it.
- Run the strict site build. Fix missing files and heading fragments at the source. Never weaken validation to accommodate a stale link or turn an unverified historical result into acceptance.
- Review desktop and narrow/mobile navigation, search results, code fences/tables, light/dark mode, images, archive notices, and GitHub source/edit links in the browser.
Visual system and navigation¶
The field-guide homepage lives in home.md, with semantic HTML for its hero, real command
examples, task-based entry cards and knowledge links. It remains the canonical content; there is no separate
marketing page or generated copy to maintain. Its metadata hides the article table of contents; CSS hides
the desktop sidebar only, keeping the mobile drawer reachable. A small theme/main.html
override adds the homepage's keyboard skip link while retaining Material's standard header.
assets/wiki.css provides the Summon visual identity: system typography, violet accents,
coordinated light/dark surfaces, readable code/tables, focus outlines and reduced-motion handling. It also
styles the reading pages without replacing Material's search, drawer, keyboard behavior or Mermaid integration.
Brand logo/favicon are staged explicitly from Summon's existing original artwork. No new font service,
JavaScript bundle or frontend dependency was added.
The five top-level destinations are Overview, Get started, Use SummonOS, Build apps and Knowledge base. Historical archive content remains explicitly labeled inside the knowledge base. Every discovered public page stays in navigation and search. Check mobile nested navigation as well as the desktop tabs when changing these groups; the mobile drawer uses Material's native controls.
Navigation uses readable top-level groups and automatically appends new public pages. Adjust deliberate
prominent-page ordering in navigation() when needed; change the public selection rules only when the
new source belongs in the published wiki. mkdocs.yml owns theme, search, Markdown
extensions, canonical URL, and strict validation settings. GitHub-style fenced blocks and tables render
as code and tables. Mermaid fences use Material's native diagram integration,
including light/dark styling, without custom JavaScript. Other fence languages remain code rather than
becoming raw HTML.
Material loads Mermaid's runtime from its CDN when a diagram page opens; diagram rendering therefore needs network access. Navigation, search, theme assets and ordinary document content are served from the built site.
CI and publishing¶
The Documentation workflow validates documentation-related pushes, pull requests and manual runs with the same strict build. Its repository permission is read-only; it does not publish artifacts to GitHub Pages or request deployment privileges.
Vercel¶
The canonical website URL is https://sumonos.rohi-lab.org/. The hostname deliberately uses
sumonos, as selected by the owner. vercel.json configures a static site:
- Framework preset: Other; use the repository root, not
docs/. - Install: pinned documentation dependencies into the ignored
.vercel/pythondirectory. - Build: the canonical
tools/docs-site.pywrapper generates and validates the complete site in a fresh external temporary directory, then copies the finished HTML/assets into ignoredpublic/. - Output:
public/, served with trailing-slash document URLs. - Production branch:
main; other branches can produce review previews when Git integration is connected.
The custom domain must be attached to this Vercel project and its exact DNS record must match Vercel's project-specific recommendation. Do not change the apex domain or another project's DNS records. GitHub Pages is not required and the old Pages deploy job has been removed to avoid competing publishers. Application releases and their Stable/Edge channels remain separate from website deployments.
Web Analytics and footer¶
Every page carries the owner's footer: Powered by caffeine and questionable life choices.
Vercel Web Analytics uses the provider's native static-HTML script, with no React or Node dependency.
Enable Web Analytics for the summonos project in Vercel; deployed builds include the script when
Vercel sets VERCEL=1. Local builds omit tracking by default. VERCEL=1 can exercise the deployed
HTML configuration locally, but the analytics endpoint itself is supplied by Vercel at runtime.
Only that exact opted-in script endpoint is treated as runtime-owned by link validation; other
missing assets and links still fail. Live verification must confirm the script is actually served.
No custom events, Speed Insights, or paid Analytics Plus add-on is enabled.
A successful local build is not proof of publication. Verify the Vercel deployment's commit and Ready state, the custom domain's DNS/TLS, and the actual homepage, reading routes, images and search in a browser. Before advertising the domain, confirm anonymous access without a Vercel sign-in redirect.
Local Vercel linkage/credentials, generated HTML and internal review reports must never be committed or copied into the public documentation tree. Only the selected public source mapping above is published.