Installation

starting a wiki in a project

Contents

1Requirements
2Wrapper
3First wiki
4Updates
5References

wiki-builder is one Python package, and its only command is wiki.^[1] What each command does is described on Commands, and checking a wiki on every push on Continuous integration. An agent can take a project through every step below from the Installation prompt.

Requirements

It needs Python 3.11 or newer, and one dependency pinned exactly, the markdown parser mistune.^[1] The wrapper script below also needs uv, whose uvx runs a release straight from its git address; a project without uv installs a release with pip and runs wiki directly.^[2]

Wrapper

A project commits one script that runs a pinned release, and passes --root so the tool finds the project wherever the script is called from.^[3]

#!/bin/sh
# scripts/dev-wiki.sh
set -eu
WIKI_VERSION=TAG
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
exec uvx --from "git+https://github.com/timothymarois/wiki-builder@$WIKI_VERSION" \
     wiki "$@" --root "$ROOT"

The tool accepts --root after the command, which is what lets the script add it to whatever it is handed.^[3] TAG names a published wiki-builder release.^[?]

First wiki

The tool reads a wiki from docs/wiki unless told otherwise.^[4] That folder needs a wiki.toml with a site name and at least one section, or the tool stops and says so.^[5]

[site]
name = "Notes"

[[section]]
title = "Start"
pages = ["index", "goals"]

Every wiki needs a goals.md page to collect the intents onto, and every page needs a title and an intent.^[6] Every page a section lists must exist, so the example above also needs an index.md.^[7] A page about the wiki itself says goals = false.^[8]

+++
title = "Goals"
status = "approved"
goals = false
intent = """
This page collects what each part of the project is for.
"""
+++

What each part is for.

wiki sync writes the skill for the project's agents and records the release, then wiki build records each page's date.^[9] The tool writes no ignore file, so a project adds docs/wiki/site/ to its own .gitignore to keep the rendered site out of version control, as wiki-builder does.^[10]

./scripts/dev-wiki.sh sync
./scripts/dev-wiki.sh build
./scripts/dev-wiki.sh check

Updates

An update is a new tag in the script, then wiki sync to rewrite the skill and record the release.^[9] wiki check fails until that release is recorded, and names every page a new rule breaks.^[11]

References

pyproject.toml — [project.scripts] names the wiki command, requires-python asks for 3.11 or newer, and dependencies pins mistune==3.3.4.
uv docs — Tools: uvx is an alias for uv tool run, and --from installs a tool from another source, such as a git repository; action.yml — installs wiki-builder with pip, without uv.
src/builder/cli.py — main() accepts --root and --wiki before the command or after it.
src/builder/build.py — wiki_of() defaults the wiki to docs/wiki.
src/builder/config.py — read_config() refuses a wiki.toml with no site.name or no [[section]].
src/builder/build.py — write_site() refuses a wiki with no goals.md, and read_pages() refuses a page with no title or intent.
src/builder/build.py — render_nav() refuses a section listing a page that does not exist.
src/builder/build.py — goals = false is skipped by goals_page() and uncited_problems().
src/builder/cli.py — sync() writes the skill and calls record_version() in src/builder/config.py; src/builder/build.py — write_site() records dates in UPDATED.toml.
.gitignore — docs/wiki/site/; src/builder/cli.py — run() builds into site inside the wiki folder, and nothing in src/builder writes a .gitignore.
src/builder/build.py — version_problems(), called from check(), which gathers every problem at once.

Last updated 14 September 2026307 wordsabout 2 minutes to read11 sources cited1 claim with no source