04 Wiki Workflow

Wiki workflow

The wiki is maintained from the repository: pages live in wiki/, order is set by wiki/wiki.json. Publication is a separate step performed by the pack.

Why not edit the wiki on GitHub

Approach	Problem
Editing in the wiki web interface	drifts from the repository, no review
Pages copied in two places	a month later they differ
Publishing by hand with git clone .wiki.git	the verification step is forgotten and foreign pages are lost

The pack keeps the source in the repository, where review and CI work, and the wiki receives a built tree.

Build

python tools/ghagent.py wiki build
python tools/ghagent.py wiki verify

What build does:

1. Reads wiki/wiki.json; every manifest entry must exist.
2. Every file in wiki/ must be listed — otherwise "the page is invisible", which is an error.
3. Rewrites links: internal ones lose .md, links into the repository tree become absolute https://github.com/<owner>/<repo>/blob/<branch>/….
4. A relative image is an error: the wiki repository cannot see the project tree.
5. Generates _Sidebar.md from the manifest groups and _Footer.md with repository links.

verify checks the built tree: required files, links to existing pages, no .md inside internal links, no relative images, an H1 per page, every page reachable from navigation.

Publish

python tools/ghagent.py wiki publish --repo owner/name            # dry run
python tools/ghagent.py wiki publish --repo owner/name --push     # publish

Flag	Effect	When
no flags	commits into the local clone, sends nothing	always first
--push	sends to <repo>.wiki.git	after reading the dry run
--prune	deletes remote pages absent from the build	deliberately, never by habit
--force	publishes even when verification failed	almost never
--author-name, --author-email	the commit signature	the owner's identity, not the agent's

Output: added, modified, kept pages and the commit hash. Pages on the server that the build does not contain are kept by default, so foreign work is never lost silently.

The first publication needs one manual step: <repo>.wiki.git is created by GitHub only when a first page is saved in the web interface, and git push cannot create it. Until then the command returns wiki.remote-missing with that instruction.

What to write on a page

1. H1 — the page name, matching the filename without .md.
2. A paragraph: why this page exists.
3. A table or a list: specifics, not reasoning.
4. A language-tagged code block for every command.
5. At the end, a link to the next page or the repository.

Translations

English pages are canonical. A Russian translation is a separate page with the .ru.md suffix and appears in navigation under its own group. Build and verify treat both exactly the same way: a translation gets no exemption from link and image rules.

Traps

Trap	Symptom	Action
The wiki repository does not exist	remote: Repository not found on publish	save the first page in the web interface, then publish
A link with .md	raw file or 404	drop the extension
An image inside wiki/	does not render	move it into the repository tree, reference absolutely
A page missing from the manifest	absent from navigation	add it to wiki.json
A Cyrillic anchor	#Установка is not found	compare case-insensitively, write it as the heading reads
--prune without reading the list	a page is gone	restore it from the wiki repository history

Next

• Release.
• Platform traps.