Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Documentation Workflow

The published documentation is organized as a system manual first. The top of docs/SUMMARY.md should lead with pages that explain how to understand, build, boot, configure, operate, and review the current capOS implementation.

The mdBook site may keep the wider project corpus reachable for maintainers: roadmap, changelog, backlog, proposal, paper, and research files can remain under the lower archive section. Those pages should not shape the primary reader path, and they should not be treated as part of the generated PDF manual unless they become current system documentation.

PDF Manual Pipeline

The PDF is a Typst-authored manual shell plus generated body content:

  1. tools/docs-bundle.js reads docs/SUMMARY.md, selects only manual sections, rewrites bundled-doc links to PDF-local heading anchors, and emits ignored Markdown at docs/capos-docs.md.
  2. mdbook-mermaid checks Mermaid syntax, and mermaid-cli converts Mermaid blocks in the generated Markdown to PNG artifacts under target/docs-bundle/.
  3. uv tool run --constraints tools/md2typst-constraints.txt --from md2typst==0.3.3 md2typst converts the generated Markdown body to Typst with the converter dependency set pinned.
  4. tools/build-typst-manual.js normalizes the converted body, fills docs/manual.typ with the generated version/date/source metadata, and writes target/docs-bundle/capos-docs.pdf.typ. The normalizer also collapses Markdown source-wrap line breaks outside code blocks so PDF prose and list items use normal paragraph layout.
  5. The pinned Typst binary compiles the final PDF.

docs/manual.typ owns the PDF document structure: title page, version block, one-level table of contents, page setup, and base typography. Generated files under docs/capos-docs.md, target/docs-bundle/, and target/docs-site/ must remain untracked.

Scope Rules

The PDF manual includes current system documentation: introduction, status, build and boot workflow, configuration, repository map, runnable demos, architecture, and security/verification pages.

Project archives stay on the mdBook site but are excluded from the PDF manual: proposals, backlogs, research notes, whitepaper planning, and other planning records are useful context for maintainers, not the operator-facing manual.