Contribute to the documentation
The documentation lives in Markdown files in docs/. The same files are also published as a website using VitePress. To update the documentation, edit the Markdown files; you do not need JavaScript or VitePress knowledge or a local website setup. CI builds the website from PRs that change docs/ to check that the documentation builds correctly.
Include documentation changes in feature and fix PRs when they affect how people use the project; documentation-only improvements are also welcome.
Choose the right page
Update existing coverage where appropriate. For a new page, choose a category by the reader's purpose.
Diátaxis distinguishes learning from working, and practical action from theoretical knowledge. Tutorials involve doing too; the distinction is whether the reader is acquiring skills or applying them.
| Category | Reader's purpose | Approach | What the page provides |
|---|---|---|---|
| Tutorials | Learning | Practical action | A guided exercise through which the reader acquires skills. |
| How-to guides | Working | Practical action | Directions for completing a specific task using existing skills. |
| Reference | Working | Theoretical knowledge | Precise information to consult while applying existing knowledge. |
| Explanation | Learning | Theoretical knowledge | Context and reasoning that develop the reader's understanding. |
Place the page in the corresponding directory:
docs/10-tutorials/: Tutorials.docs/11-how-to/: How-to Guides.docs/12-reference/: Reference.docs/13-explanation/: Explanation.
Keep each page focused on one reader need. Split substantial sections that serve different needs into separate pages and link between them. Short prerequisites, examples, and supporting context can stay with the page they help. See the documentation contribution guidelines for the placement policy.
Category indexes should briefly explain their purpose rather than list every document.
Write Markdown that works on GitHub and the site
Follow the directory's numbered kebab-case naming convention, for example
01-contribute-documentation.md. The sidebar orders folders and files by name.Start the file with YAML frontmatter containing a short sidebar title. After the frontmatter, add one main
#heading:markdown--- title: Short Sidebar Title --- # Main Page HeadingUse
##and###headings to organize sections, backticks for inline code, and fenced code blocks with a language such asshfor commands. Keep Markdown compatible with GitHub; use VitePress Markdown extensions only when they preserve that compatibility.Link to documentation using relative
.mdpaths, for example[Environment variables](../02-setup/04-env-variables.md). A#heading-fragmentcan link to a specific section. Check that the target file and heading exist.Put article images in
docs/images/and use relative paths with descriptive alternative text, for example. Reservedocs/public/for site assets.State prerequisites and expected results for instructions. Clearly identify destructive operations. Keep commands, configuration names, and examples consistent with the repository's behavior.
Add diagrams
Use fenced mermaid blocks with standard Mermaid syntax. Include accTitle and accDescr for accessibility. Check diagrams in the local preview, including light/dark readability when adding custom colors. We use Pele, so Mermaid theme settings such as themeVariables do not apply.
Check the documentation
Review the Markdown preview in your editor or on GitHub. Check heading levels, code fences, tables, links, and images.
Follow the repository's existing pre-commit requirements and commit conventions. Documentation changes accompanying a feature or fix belong with that change; they do not require a separate documentation branch or PR.
The PR must pass the lint and documentation build checks. CI builds the site and reports errors such as broken page links or invalid Markdown syntax. If a check fails, read its log, correct the affected source, and push the fix. CI does not verify every heading fragment, so check those yourself.
Maintainers working on site configuration can use the specialist Configuring VitePress guide.