Documentation site

Edit the Markdown in docs/. VitePress builds the public site from those files.

Preview

From the repository root:

npm ci
npm run docs:dev

Open the printed localhost address. To check links and build static HTML:

npm run docs:build

The preview command serves the site on localhost. The production build goes to docs/.vitepress/dist/. The build checks local page links and writes redirects from the previous MkDocs URLs. Links to files outside docs/ should point directly to their source on GitHub.

Publish

The Documentation workflow checks pull requests and deploys changes merged to main to the Cloudflare Pages project gnoblin-docs.

Set these repository values in Settings → Secrets and variables → Actions:

Name	Type	Value
CLOUDFLARE_API_TOKEN	Secret	Token with Account → Cloudflare Pages → Edit access
CLOUDFLARE_ACCOUNT_ID	Variable	Cloudflare account ID that owns gnoblin-docs

The APT archive continues to use the gh-pages branch independently.

Write for the reader

• Give each page one job. Start with what the reader can do.
• Explain unfamiliar terms before using them: a reader should not need Mutter knowledge to change a titlebar.
• Give complete, runnable config examples. A variable containing settings does nothing until a config function uses it.
• State where to put an example and what should change after applying it.
• Put the normal command before implementation details.
• Use short paragraphs and one action per numbered step.
• Explain an option beside its example: accepted values, default, units and reload.
• Keep tables short. Link to details instead of packing paragraphs into cells.
• Keep user instructions separate from protocol and testing notes.
• Capture screenshots in a fresh devkit profile or VM and inspect them for personal data before publishing.
• Show real interface activity, without placeholder output. Put commands and explanatory text in prose or code blocks, not in staged terminal screenshots.
• Check published package names before updating installation commands.

Installation is organised around the package-first approach used by niri and Hyprland.

Dated experiments and superseded design proposals are kept under design/archive/ in the source repository. They are not part of the published user documentation.