Contribute to the documentation

One source of truth

User-facing documentation lives in src/content/docs/. Matching files under docs/ are compatibility pointers, not independent copies to edit. Root READMEs link to the canonical content. Historical experiments may remain beside their code and must be labeled as such.

Use one home for each fact. Link to configuration defaults, API contracts, and procedures instead of copying them into multiple guides.

Page contract

Every page needs a specific title and description. A procedure states its outcome, prerequisites, terminal/environment, steps, expected results, failure guidance, and next step. A reference states the actual implementation and its limits.

Do not mark a capability verified because a script or configuration file exists. Distinguish source review, recorded historical results, and tests actually run.

Write a lab

A lab must identify prerequisites, sample inputs, numbered actions, an artifact to produce, observable acceptance criteria, troubleshooting, and cleanup limitations. Link to shared setup instructions. Do not advertise planned exercises as available.

Use this outline when adding an exercise:

---
title: "Describe the skill practiced"
description: "Describe the observable result"
---
## Objective
What the learner will produce and why.
## Prerequisites and environment
Required setup, tools, sample data, and the terminal used.
## How it works
Components involved and the request or data flow.
## Steps
Numbered actions with commands and expected output.
## Verify the result
Specific checks and acceptance criteria; include failure cases.
## Troubleshooting and security
Likely errors, credential handling, and execution risks.
## Cleanup
Exactly which exercise resources to remove or retain.
## Next steps
Link to the next exercise and shared reference pages.

Test the exercise in a separate lab environment. Record the source revision and software versions, and distinguish steps you ran from steps checked only against source. Add the page to src/site-navigation.mjs so readers can find it.

Check your change

Use the project’s Node version and install dependencies in a clean working copy:

npm ci
npm run docs:check
npm run build
npm run docs:links
npm run preview

Check the homepage, a long reference, search, mobile navigation, and an old URL. The build creates the search index. Do not substitute the development server for a production-link check.

Navigation and redirects

src/site-navigation.mjs defines section order and legacy route destinations. New public pages must be reachable. Moving a page requires an old-route redirect and a review of important fragment links. The site uses CI_PAGES_URL when available, or DOCS_SITE_URL for an explicit deployment address; confirm the Pages URL in GitLab before publication.

Review and publication

Prepare changes on a documentation branch. Review the diff and validation evidence before committing or pushing when the operator requires approval. The default-branch Pages job publishes after merge; no backend deployment tag is needed.

Next: Project status.