Maintain the documentation site¶
The public site is deployed at
abdelstark.github.io/hallmark.
It uses Zensical 0.0.73, pinned in a separate website/ project and lockfile.
Canonical guides and research records stay in their existing Markdown files. The site stages tracked documentation, public evidence and explicit assets; it does not publish ignored runs or untracked files.
Build and preview¶
From a Git checkout, using uv 0.9.18:
The preview is at http://127.0.0.1:8000/. The second command rebuilds first,
then serves the generated site. After editing source files, run make docs
and refresh the browser. No custom watch daemon is used.
New source/asset files must be staged with git add <exact-paths> before a
local build. Modified tracked files use their working-tree contents.
This intentional boundary prevents an untracked research note from appearing
in the published site.
Where to edit¶
| Surface | Source |
|---|---|
| Homepage content | index.md |
| Homepage layout | home.html |
| Navigation and extensions | mkdocs.yml |
| Visual system | styles.css |
| Math and proof explorer | site.js |
| Figures | render_figures.py writes docs/assets/figures/ |
| Educational path | Learn |
| Evidence entry point | Research evidence map |
| Staging and validation | build script, site checker |
| Deployment | Pages workflow |
Python environments and model/proof pipelines are unchanged by a docs build.
The separate docs environment is optional; ordinary users do not install it.
The inference uv.lock and enrolled verifier identity remain unchanged.
Publishing¶
The Pages workflow builds and validates pull requests. Deployment runs only from
main or a manual dispatch targeting main, using the github-pages
environment. It uses the locked environment, pinned action commits and the
standard Pages artifact/OIDC deployment flow; no personal deployment token or
scheduled job is needed.
Keep the repository and site public. No custom domain, analytics, comments, external search account or research compute scheduler is configured.
Validation¶
make docs runs a strict site build and checks generated local links/assets
and anchors. It also checks that the homepage, search index, equations, diagrams
and model links are present. Unit tests exercise tracked-file selection,
link rewriting and rejection of unsafe staging inputs.
Before publishing, review a desktop and narrow viewport, navigation/search, code copying, theme switching and the educational proof selector. Verify the hosted deployment and live paths after merging.
Figures¶
The diagrams and charts in docs/assets/figures/ are generated, never drawn by
hand. render_figures.py reads the frozen records
in research/evidence/ and the fixed LLM case, and writes self-contained SVGs
that switch to a dark palette with the reader's system theme. Chart colours
pass a colour-vision-deficiency check against both backgrounds.
python scripts/render_figures.py # regenerate
python scripts/render_figures.py --check # fail if a figure is stale
tests/test_figures.py fails when a committed figure differs from what the
evidence produces, so a changed record cannot leave an old chart behind. To
change a figure, edit the script and regenerate; do not edit the SVG. Every
figure needs alt text that states its numbers, and a table or prose nearby
that carries the same values.
Asset provenance and claims¶
Fonts and KaTeX are self-hosted. Their licences, original release URLs, package-integrity values and per-file SHA-256 hashes are in asset provenance. Zensical provides the search/navigation and Mermaid integration.
Keep every performance number linked to a recorded measurement and state its boundary. Do not turn a software check, model download, native rerun or hash receipt into a proof or hardware claim. Older protocols/decisions remain dated research records; never rewrite numeric evidence to make the site look cleaner.