This repository publishes docs/wiki/ using docs/wiki.yml. The workflow lives at .github/workflows/deploy.yml.

Pipeline

1. uv sync — install dependencies
2. wiki -c docs/wiki.yml check --strict -v — SHACL, JSON Schema, routes, layout
3. wiki -c docs/wiki.yml build --output-dir _site --site-base-url /wiki — static HTML
4. Upload _site/wiki as the Pages artifact
5. deploy-pages — publish

Enable GitHub Pages → Build and deployment → GitHub Actions in repository settings.

Local preview

wiki -c docs/wiki.yml serve
# http://127.0.0.1:8080/wiki/

Custom wikis

For your own wiki, copy the workflow and change:

• -c path to your config
• --site-base-url to match your Pages path (/wiki, /my-wiki, or '' for root)
• path in upload-pages-artifact to the directory that contains your built index.html

See Wiki Subcommand build for site.url_style, wiki.assets, and collision checks.

Avoid these mistakes

When using upload-pages-artifact and deploy-pages:

• Do not commit _site/ to main — add _site/ to .gitignore and let CI build the artifact
• Do not use Deploy from a branch in Pages settings — use GitHub Actions as the source
• Do not use peaceiris/actions-gh-pages or push to a gh-pages branch for this pattern
• Do not set artifact path to _site when site.base_url is /wiki — upload _site/wiki instead
• Do not run uv sync in CI unless the repo has pyproject.toml and uv.lock
• Do not use uv pip install on standalone wikis without uv venv or --system — use pip install wazootech-wiki instead
• Do not hybridize install steps — embed skills/wiki/references/workflow-template-uv.yml or skills/wiki/references/workflow-template-pip.yml wholesale and substitute paths only (see Wiki Skill)

Verify Pages is wired to Actions: gh api repos/{owner}/{repo}/pages --jq '{build_type, source}' should show build_type: workflow.

Agent skill

Coding agents can use Wiki Skill (skills/wiki, deploy reference) to scaffold the workflow and align artifact paths.

Related

• Getting Started
• Wiki Configuration
• Wiki Skill