Skip to content

Wiki Publishing

github-actions[bot] edited this page Oct 27, 2026 · 3 revisions

Wiki publishing and documentation coverage

Repository Markdown is the source of truth. The GitHub wiki is generated by tools/wiki_sync.py, not a separate set of hand-maintained documents. Edit the original file and publish it through the repository.

What is published

Every tracked Markdown document is mapped in SECTIONS in tools/wiki_sync.py, including the root project policies, docs/ and guides, port READMEs, Studio and template authoring, examples, benchmark instructions and regression-fixture READMEs. The generated Home and sidebar group the pages; relative document links become wiki links, while source-code links point to GitHub and images to the raw source.

A missing document mapping, missing source file, duplicate/reserved page name, broken relative file link or invalid heading anchor fails the check. New non-ignored Markdown files are checked locally too. Generated/downloaded ignored build files are not published.

make docs-check              # inventory, links, anchors, wiki tests, template bundle
python3 tools/wiki_sync.py --out build/wiki

Add a new document to the relevant SECTIONS group with a unique stable wiki page name, then link it from the documentation index. Rename a wiki page only when necessary, because external links may use its old name. Do not edit generated docs/STDLIB.md directly: update tools/gen_stdlib_doc.py or the API metadata, then run:

python3 tools/gen_stdlib_doc.py > docs/STDLIB.md

Publishing

The Wiki workflow publishes documentation pushes to main; it can also be run manually in Actions. Select the intended source branch. A non-main publication is clearly marked as a development preview, not a released API. The workflow sets source links to that branch and records the exact source revision in the generated footer. Preview publication replaces the public wiki until the next publication, so use it deliberately; rerun the workflow on main to restore stable docs.

The workflow uses its existing repository GITHUB_TOKEN with contents: write. No account password or personal access token should be placed in source files, workflow YAML, scripts or generated wiki pages. The wiki must already have its first page; if cloning/pushing fails, inspect the Actions error and repository permissions.

Wiki-only edits are overwritten by the next generated publication. The publishing job replaces generated Markdown pages, so keep documentation changes in the repository.

Clone this wiki locally