wiki.toml

the settings file for a wiki

Contents

1Location
2Keys
3Validation
4Example
5References

wiki.toml holds a wiki's name, its sidebar sections, its reading budgets and the release it was last synced with.^[1] How budgets are enforced is described on Reading budgets, and how pages nest beneath a section on Pages.

Location

The file sits in the wiki folder, docs/wiki/wiki.toml unless --wiki names another folder, and is read as TOML.^[2]

Keys

Key	Type	Default	Meaning
`site.name`	string	required	the name at the top of the sidebar and in every tab title^[1]
`site.tagline`	string	none	a line under the name in the sidebar^[1]
`[[section]]`	table, repeated	required, at least one	a group in the sidebar, in the order written^[3]
`section.title`	string	empty	the group's heading^[3]
`section.pages`	list of page names	none	the pages that start a branch, by path without `.md`, such as `checks/budgets`^[3]
`section.categories`	list of category names	none	categories linked from the sidebar^[3]
`budget.page`	whole number	500	words a page may use^[4]
`budget.intent`	whole number	120	words an intent may use^[5]
`budget.goals`	whole number	3500	words the collected goals may use^[6]
`budget.calibrated`	true or false	false	whether the budgets have been measured against a reader^[7]
`tool.version`	string	none	the release `wiki sync` recorded^[8]

Any other key is ignored.^[1] A section that lists nothing gets no heading in the sidebar.^[3]

Validation

Every problem below stops the build, except a missing or different tool.version, which wiki check lists with the rest.^[8]

Condition	Message
the file is missing	`wiki: there is no wiki.toml in /path/to/notes/docs/wiki`^[1]
the file is not valid TOML	`wiki: wiki.toml is unreadable:` and the parser's error^[1]
`site.name` is missing or empty	`wiki: wiki.toml has no site.name`^[1]
there is no `[[section]]`	`wiki: wiki.toml lists no sections, so nothing would be reachable`^[1]
a budget is not a positive whole number	`wiki: wiki.toml: budget.page must be a positive number of words`^[1]
a section lists a page that does not exist	`wiki: the navigation lists a page 'nope' that does not exist`^[3]
a section lists a category no approved page carries	`wiki: the navigation lists a category 'Payments' that no page belongs to`^[3]
`tool.version` is missing	wiki: wiki.toml does not say which release of the tool these pages were written against; run `wiki sync` ^[8]
`tool.version` names another release	wiki: these pages were written against wiki-builder 0.0.9 and this is 0.1.0; run `wiki sync`, then expect any rule added since to be enforced here^[8]

Example

wiki-builder's own wiki runs on the default budgets; two of its sections are shown here.^[9]

[site]
name = "wiki-builder"
tagline = "the tool's own wiki"

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

[[section]]
title = "Reference"
pages = ["commands", "wiki-toml", "front-matter", "pictures-toml"]

[tool]
version = "0.1.0"

References

src/builder/config.py — read_config() reads site, section, budget and tool and nothing else, and raises the first five messages; src/builder/build.py — render_page() puts site.name in the sidebar and the tab title, and site.tagline beneath the name.
src/builder/config.py — CONFIG, read from the wiki folder by read_config() with tomllib; src/builder/build.py — wiki_of() defaults that folder to docs/wiki.
src/builder/build.py — render_nav() writes each section's title over its pages and categories in order, skips a section with neither, and raises for a page or category that does not exist.
src/builder/config.py — DEFAULT_BUDGET, under which read_config() merges [budget].
src/builder/config.py — DEFAULT_BUDGET sets 120; src/builder/build.py — read_pages() refuses an intent that runs over it.
src/builder/config.py — DEFAULT_BUDGET sets 3500; src/builder/build.py — budget_problems() refuses collected goals that run over it.
src/builder/config.py — DEFAULT_BUDGET sets it false; src/builder/build.py — report() calls the budgets provisional on every run until it is true.
src/builder/build.py — version_problems(), called from check(); src/builder/config.py — record_version(), called by wiki sync, writes tool.version.
docs/wiki/wiki.toml — no [budget] table.

Last updated 14 September 2026Last audited never499 wordsabout 2 minutes to read9 sources cited0 claims with no source