The repository is the source of truth for the public BaudBound wiki. Contributors edit Markdown under wiki/. The publisher validates it, converts repository links to Wiki.js paths, reconciles managed pages, and updates the static navigation.
Do not make an important documentation fix only in the Wiki.js editor. A later repository publication will replace managed page content with the committed source.
Assume the reader has never used BaudBound and may not know the operating-system tool being discussed. Introduce BaudBound terms before depending on them and link to Concepts and Glossary instead of repeating partial definitions.
Every procedure must state:
Use short sentences and one action per numbered step. Put commands in fenced code blocks. Prefer familiar file commands such as mkdir, cp, mv, chmod, and chown in beginner procedures. Do not hide decisions inside shell conditionals merely to shorten instructions.
Do not use semicolons or dash punctuation in normal prose. Start a new sentence instead. Hyphens that are required inside commands, options, paths, identifiers, and established technical names must remain exact. Markdown list markers are also allowed because they render as list structure rather than punctuation.
Explain destructive consequences before a command that deletes, overwrites, resets, revokes, or exposes data. Follow the command with a verification step.
Use uppercase placeholders consistently:
| Placeholder | Meaning | Example replacement |
|---|---|---|
SCRIPT |
Installed script name or ID | hello-baudbound |
PACKAGE |
Path to a .bbs package |
C:\Users\Alice\Downloads\hello.bbs |
TRIGGER |
Trigger node ID | n-mr3zyt6f-1 |
SECRET_NAME |
Declared secret name | api_token |
DEVICE_ID |
Logical serial device ID | workbench-scale |
PATH |
Context-specific filesystem path | ~/.local/opt/baudbound/BaudBound.AppImage |
State that the placeholder must be replaced before showing a command. Do not wrap a placeholder in angle brackets because shells can interpret < and > as redirection.
When a literal value is required by the product, use lowercase or a realistic value rather than the placeholder convention. For example, a tutorial can intentionally use the webhook hook name tutorial.
Public pages live under wiki/**/*.md. Directory index.md files publish at the directory path:
| Source file | Wiki.js path |
|---|---|
wiki/home.md |
/home |
wiki/getting-started/index.md |
/getting-started |
wiki/runner/installation.md |
/runner/installation |
Each page requires YAML frontmatter:
---
title: Page title
description: One sentence used for page metadata and discovery.
tags: [runner, reference]
---
Supported optional fields are published, private, locale, and tags. Unknown fields fail validation. Use kebab-case filenames and paths. Avoid renaming a published path without a migration reason because existing bookmarks and external links will break.
Write internal links to repository Markdown files:
[Installation and Updates](../runner/installation.md)
[Configuration](../runner/configuration.md#serial-device-model)
The publisher verifies the target page and rewrites it to the managed Wiki.js path. Root-relative Wiki.js links are also accepted when they point to a managed page, but source-relative Markdown links are easier to review during file moves.
External web links must use HTTPS. mailto: and tel: are accepted only for normal links, not images. Link to primary documentation for platform behavior, formats, and dependencies. Do not use a search results page as a source.
The publisher currently verifies that external links have valid syntax, but it does not guarantee that every remote server is reachable. Review important external links manually.
Use a component when it makes a decision or warning easier to understand. Do not add components only to decorate a page.
Use tabsets for mutually exclusive paths such as Windows and Linux, or systemd and OpenRC. Keep shared steps outside the tabs.
## Choose a platform {.tabset}
### Windows
Windows instructions.
### Linux
Linux instructions.
Do not use tabs when readers need to compare both values at once. Use a table instead.
Write in short, direct sentences. Do not join list items with semicolons. Avoid dash asides when a separate sentence is clearer. Keep punctuation required by commands, code, paths, and configuration exactly as written.
Use an information callout for context that affects a decision:
An AppImage is a portable executable and is not installed by a package manager.
{.is-info}
Use a warning callout for data loss, secret exposure, network exposure, stale approval, or an operation that can affect another application:
Binding to `0.0.0.0` can expose the listener to other machines.
{.is-warning}
The warning must explain the consequence and the safer next action.
Use tables for field references, comparisons, support matrices, and compact definitions. Keep procedural steps in numbered lists.
Add a language to fenced code blocks when syntax highlighting helps, such as toml, json, yaml, powershell, bash, rust, or typescript. Use text for output and commands intended to be identical across supported shells.
Mermaid diagrams may be used only after the production Wiki.js renderer has been tested with the required syntax. Every diagram needs a text explanation so its information remains accessible and useful outside the rendered wiki.
Store local documentation images only under wiki/assets/. Supported formats are PNG, JPEG, and WebP, with a maximum size of 2 MiB per file. SVG is intentionally rejected because active or externally referenced content is harder to audit safely.
Reference an asset relative to the page:
The publisher verifies the path, type, and size, then rewrites it to the repository-controlled HTTPS asset base. WIKI_ASSET_BASE_URL may override that base for a reviewed deployment. Missing, oversized, unsupported, insecure, or out-of-directory images fail validation.
Use screenshots for spatial orientation rather than as the only record of labels, commands, or settings. Crop usernames, paths, package IDs, network data, and secrets. Add useful alternative text. The contributor who changes the pictured UI owns updating or removing its screenshot.
wiki/navigation.json is the source of truth for the Wiki.js sidebar. Every managed page in its locale must appear exactly once.
Each item has a stable kebab-case ID. Link items also require a label, managed page path, and Material Design icon beginning with mdi-. Headers group related pages but do not replace a landing page.
The publisher rejects:
Changing an ID can cause unnecessary Wiki.js navigation replacement. Keep the existing ID when only a label or target title changes.
The publisher adds baudbound-docs and managed-by-git tags. It updates or deletes only pages under that ownership contract.
A matching unmanaged Wiki.js page is not overwritten unless explicit adoption is enabled for a reviewed run. Managed page deletion has a safety limit. A larger reconciliation requires an explicit mass delete option. The publisher reads remote navigation during preflight and updates page content before reconciling the static tree.
Dry-run publication calculates page and navigation changes without mutating Wiki.js. Use it when adopting pages, changing many paths, or reviewing a potentially destructive reconciliation.
Install the pinned publisher dependencies once:
pnpm --dir publisher install --frozen-lockfile
Run the publisher safety contracts and full documentation validation:
pnpm --dir publisher test
pnpm --dir publisher validate
Validation checks metadata, page paths, internal links, HTTPS policy, assets, navigation completeness, required pages, and publisher safety contracts. It also reads the current editor node definitions and the runner desktop navigation, CLI, configuration, permission, and capability contracts. A changed source fingerprint or an undocumented product identifier fails validation. It reports the source file and line for content errors where available.
Local source-derived validation expects sibling editor and baudbound repositories by default. Set WIKI_EDITOR_SOURCE_ROOT and WIKI_RUNNER_SOURCE_ROOT when the repositories are elsewhere. CI checks out the current master of both product repositories into isolated source directories before validation.
Do not solve a coverage failure by deleting a source from the manifest. Add or correct the public documentation, or update the baseline only when a reviewed product surface was intentionally removed.
navigation.json with a stable ID and relevant icon.Never delete a page merely because it is short. First decide whether it should be expanded, merged into a stronger task page, or retained as a useful landing page.
The Wiki Documentation workflow runs publisher tests and validation for every pull request and push. A weekly scheduled run checks for documentation drift against current product sources without publishing. A push to master publishes after validation succeeds. Manual dispatch can publish or perform a dry run through the protected environment.
The wiki-production GitHub environment provides:
| Setting | Purpose |
|---|---|
WIKI_URL secret |
HTTPS root URL for the Wiki.js instance |
WIKI_API_TOKEN secret |
GraphQL access for page read/write/delete and navigation management |
Manual workflow dispatch supports dry runs, reviewed adoption of matching unmanaged pages, and an explicit mass-delete override.
Before merging documentation:
As documentation coverage automation is added, its source inventories and generated-reference checks become mandatory parts of this checklist.