wiki-publish

name	wiki-publish
metadata	{"version":"0.24.6"}
description	Publish docs (roadmap, plans, user guide, status) to the team's configured wiki. Use when asked to publish/sync docs to the wiki, after cutting a roadmap snapshot, or when a plan/status report should be visible outside the repo.

Wiki publish

No per-system code ships with this skill. Read the config, then use whatever tooling exists for that system — you already know these platforms.

0. The publish manifest drives the publish set

If docs/.index/publish-manifest.json exists (generated by worklog ia-render), it IS the publish set — use it instead of the implicit default set in §4. For each manifest page:

• source is the file to publish, page_name the wiki page name, title the display title. The sidebar entry publishes as _Sidebar.md.
• render: "as-is" — publish the file as-is (frontmatter-strip rules of §3 still apply).
• render: "doc+banner" — strip frontmatter per §3, then prepend the page's banner line plus a blank line. Banners are publish-time renders; never write them into docs/ sources (frozen docs stay frozen).
• Skip rule uses render_hash, not source_hash: publish a page when the ledger entry's render_hash differs from the manifest's (or the ledger has none), and record render_hash alongside source_hash in the ledger entry afterwards. This is deliberate: a frozen page's source never changes, but its banner can (e.g. a plan becomes superseded) — the rendered overlay must reach the wiki even though the source is untouched.
• The frozen guard reads the manifest's source_hash, and that is a BODY hash. frozen: true still guards the source: if a frozen page's source_hash differs from the ledger's, stop and report it — that is a frozen-doc edit, not a render update. Take the value from the manifest; never hash the file yourself. The manifest hashes the doc below its front matter, because you strip front matter anyway (§3), so two files differing only there publish identically. That makes this guard mean the prose changed — the thing §15.8/§15.9 protects — instead of firing on every metadata stamp the normalizer, adr.mark_superseded, or a provenance backfill writes.
• Never publish docs/.index/ internals: only docs/.index/rendered/*.md listed in the manifest reaches the wiki. The JSON/YAML files (inventory, graph, manifest, aliases, sidecars) are internal join data.

Run worklog ia-index first if the manifest is stale (worklog ia-render --check tells you).

1. Read the config

Read the wiki: block in .work/config.yml. system names the wiki: github-wiki, gitlab-wiki, ado-wiki, confluence, other, or none. If it is none or absent, say so and stop — there is nothing to publish to. The enum is advisory — other is any wiki not listed (Notion, MediaWiki, a docs site): set it, name the real system in options:, and resolve the tooling at runtime like any other system below.

2. Pick the tooling

Use whatever is available for the configured system, in order of preference: a CLI already installed, an MCP server, or an installed skill.

github-wiki

gh/git: clone <origin>.wiki.git into the gitignored .work/wiki-checkout/, copy page files in, commit, push. Page namespace is flat — no directories: the filename IS the page name (User-Guide.md → "User Guide"). The wiki repo's default branch is master. Cross-page links use [[Page-Name]] syntax. Pull before pushing — the checkout is a cache; pages may have been edited in the web UI.

gitlab-wiki

Also a git repo: clone <project>.wiki.git, then copy/commit/push exactly as for github-wiki. Or use REST via glab api projects/:id/wikis. The page slug is the filename (minus .md). Unlike GitHub, GitLab wikis support directories, so nested paths work.

ado-wiki

Two kinds. A project wiki is backed by a hidden git repo — clone it via the wiki's git URL and push like any git-backed wiki. A code wiki publishes a folder on a branch — if the team uses one over docs/, committing docs IS publishing; still record ledger entries. For the REST path: az devops wiki page create/update --wiki --path --content. Page paths are hierarchical (/Parent/Child).

confluence

Needs a space key and parent page id — read them from wiki.options in the config. Prefer an Atlassian MCP server or an installed Confluence skill; otherwise use REST (/wiki/rest/api/content), which takes storage format — convert the markdown, or use a converter the team already has. If no conversion tooling exists, say so and ask rather than publishing mangled markup. Page identity is the content id — store it as page_id in the ledger entry. The version number increments on every update — store it as rev.

If tooling is missing, RESEARCH it (docs/web) and tell the human what to install — do not guess blindly. These are mainstream systems; rely on model knowledge plus live exploration, not shipped integration code.

3. Strip frontmatter for Gollum-style wikis

Plans, ADRs, status reports, and design docs carry a YAML frontmatter block (--- ... ---) as their machine-readable source of truth — never touch that in docs/. But Gollum (GitHub wiki, and any other Gollum-style wiki) renders it as raw text instead of parsing it, so the page opens with an ugly --- block up top. Fix it in the copy, not the source: for github-wiki (and other systems that are Gollum-backed), when writing a page into the wiki checkout, strip the leading frontmatter block first — only when the file starts with a --- line at byte 0, delete through the next line that is exactly ---, and write what remains. A doc with no frontmatter, or where --- appears later in the body, is untouched. gitlab-wiki, ado-wiki, and confluence understand or can be given frontmatter, so keep or adapt it per platform instead of stripping.

4. Maintain the ledger

.work/published.json maps logical keys to what was published:

{"<logical-key>": {"source": "repo/path.md", "url": ..., "rev": ..., "source_hash": "the manifest's body hash", "render_hash": "the manifest's render_hash"}}

Entries carry a source field (the repo path of the file) so the publish set is self-describing. The DEFAULT publish set is always: the live roadmap (docs/roadmap.md), every plan in docs/plans/, every roadmap snapshot in docs/roadmap/, every ADR in docs/adr/ — republish on hash change (status flips must reach the wiki), page name ADR-NNNN-slug, ledger key adr/NNNN-slug — plus anything registered via worklog wiki-add. Plans and snapshots publish once (frozen); the roadmap and ADRs re-publish on hash change. To opt an arbitrary file in, register it: worklog wiki-add <file> --key K --title T.

When a manifest exists (§0) it is the authority: copy its source_hash and render_hash into the ledger rather than hashing files yourself. Only when there is no manifest entry — a file registered via worklog wiki-add, say — hash it directly (sha256, first 12 hex chars, of the whole file). If the ledger entry's hash matches, skip it — already published. After publishing, update the entry with the page url, the wiki revision (e.g. wiki commit sha), and the new hash. Commit published.json together with the docs it describes.

5. Ledger fields across systems

The ledger shape is fixed by spec §9.3; systems just fill it differently. url is always the page's browse URL.

• git-backed wikis (github-wiki, gitlab-wiki, ADO project wiki) — rev = wiki commit sha, page_id = filename stem (User-Guide).
• confluence — rev = page version number, page_id = content id.
• ado-wiki via REST — rev = the ETag/version from the response, page_id = the page path.

6. Page naming

Derive the wiki page name from the doc title. Keep the title stable per logical key — renaming a page breaks inbound links.

7. One-time init

Surface one-time setup steps to the human; never work around them silently. Example: a GitHub wiki's .wiki.git does not exist until someone clicks "Create the first page" in the repo's wiki tab — if the clone/push fails with not-found, ask the human to do that once, then retry.

8. Frozen rules

Snapshots, plans, status reports, and dated design docs/code walkthroughs publish once and are never re-published. The live Roadmap page, ADRs, and current_design_doc / current_code_walkthrough are the exceptions: re-publish whenever the source hash changes — for an ADR, a status flip (proposed→accepted, accepted→superseded) is exactly the change that must reach the wiki.

9. Diagram assets

GitHub wiki renders fenced mermaid blocks. It does not render PlantUML source. Confluence does not reliably render either.

When a page under docs/designs/ (or a requirements doc) links an image in docs/diagrams/:

• github-wiki: copy the PNG or SVG into the wiki checkout next to the page (flat namespace) or keep a working relative link. A wiki page that points at a missing image is a publish defect.
• confluence: upload Mermaid and PlantUML images as attachments and replace source fences with the image. Do not ship a mermaid fence as the only Confluence view.
• Leave mermaid fences in the GitHub wiki copy. Leave PlantUML as an image plus the .puml source in the repo.

Missing docs/diagrams/*.png (or .svg) for a PlantUML leftover type blocks publish. Same for Confluence mermaid images.