---
title: "About these docs"
description: "Where the docs live, how the reference is generated and how to change a page."
canonical_url: "https://docs.oz0.ai/about/contributing-docs"
---
# About these docs

> Where the docs live, how the reference is generated and how to change a page.

For: Contributors changing documentation.

Documentation lives beside the product code in `docs-site/`, so behaviour and its explanation can change in the same pull request. Read the shared writing standard and documentation skill before drafting or restructuring a page. The site is built with [Docus](https://docus.dev) and published as static files.

## Change a page

Changing the docs requires access to the private repository; public source downloads are coming soon.
In your checkout, read the shared writing voice in `brand/writing.md`
and the documentation skill in `.agents/skills/oz0-docs/SKILL.md`.
Codex and Claude load the same standard through their repository skill entries.

Choose a reader and one purpose: tutorial, how-to, explanation or reference. Record the reader in `audience`,
the purpose in `doc_type`, and put a short `For:` line before the first paragraph. Put prerequisites and
warnings before the action they affect, and show how to verify the result.

Give a long explanation a named companion page. Keep technical limits, permissions and failure behaviour exact
when shortening paragraphs. Preserve the topic's URL as a useful index and link old section fragments to the
new detail. Keep executable examples with the context needed to run them.

Pages are Markdown in `docs-site/content/`, one folder per section, in the order of the sidebar: Get started, Concepts, Run, Build (with Plugins, Parts and Apps on OZ), Improve, Govern, Fleet, Spend, Admin, Reference and About. Each folder's `.navigation.yml` holds its title.

Numbered prefixes set the order and are removed from the address: `07.fleet/02.cluster/00.index.md` is `/fleet/cluster`. Use at least two digits, because names sort as text and `10.` would come before `2.`. A folder's index page uses the folder's address; the site's `index.md` is the home page.

```bash [Terminal]
cd docs-site
npm ci
npm run dev        # http://localhost:3001
```

## Move or rename a page

A page's address normally comes from its folder and its name, so moving a page or renaming it changes its address. Generated CLI pages set an explicit `path` because commands can use names that the site reserves, such as `index`. Change those paths through the generator.

Every address a page ever had keeps answering: add a row to `docs-site/redirects.yaml` with the old address and the new one,

```yaml [docs-site/redirects.yaml]
moves:
  - from: /monitor/cost-and-usage
    to: /spend/cost-and-usage
```

and the build writes a permanent redirect (301) for the page, for its Markdown copy (`/monitor/cost-and-usage.md`) and for its `/raw/` copy into the site's `_redirects`, which Cloudflare Pages applies. A page split in two keeps one row, to the page its first heading is on now, and names the headings that went to the other page under `anchors:`. Then rewrite the links to the old address, in the pages and in the rest of the repository:

```bash [Terminal]
scripts/check-docs-redirects.py --fix      # every link to a moved address, in pages, code and repository docs
make e2e-docs-redirects                    # build the site and follow every redirect, as Cloudflare Pages does
```

`make lint` runs `scripts/check-docs-redirects.py`: it fails when a page moved without a row, a row points at no page, an old address is a page again, a page links a moved address, a file of the repository names a page file that is not there, or a page sits in a folder that is no section.

## Generated pages

The [CLI reference](https://docs.oz0.ai/reference/cli/oz0) is generated from the binaries' own help text. Never edit it by hand; change the command's help in Go and regenerate:

```bash [Terminal]
make build
cd docs-site && npm run reference
```

CI regenerates it and fails if it is out of date.

## Build the site

```bash [Terminal]
cd docs-site && npm run generate    # the static site in .output/public
```

The build renders every page, and fails when one does not render or links to a page that does not exist, so a
broken page never ships as an error page. The error names the page and the page that links to it.

## Check pages against the code

Two checks keep the pages true to the binaries:

```bash [Terminal]
make build
scripts/check-docs.py        # every page's commands and flags, links and anchors, and make targets
make e2e-docs                # the check above, then the getting-started pages run as written
```

`check-docs.py` reads every command line of `orchestrator-zero` and `orchestrator-zero-node` in a page's code blocks and code spans, and fails on a subcommand or a flag the binary does not have, a link to a page or a heading that does not exist, and a `make` target the Makefile lacks.

`make e2e-docs` then runs the code blocks of the quickstart, the first plugin and joining nodes, in order and in the terminals the pages name, against a dev server whose gateway talks to a stand-in for the model provider. A block runs only when an HTML comment marks it, on the line before it; readers do not see the comment:

```md [content/01.getting-started/02.quickstart.md]
<!-- e2e terminal=2 expect="COST" -->
```bash [Terminal 2]
oz0 run hello-agent "Say hello to Ada"
```
```

The marker's options are in `scripts/docs-runner.py`: `terminal`, `background` (start it and wait for a text), `expect`, `wait-for`, `file` (write the block to the file its title names), `capture` and `sub` (replace an example value, such as a token, with a real one). When you change a marked page, run `make e2e-docs`; when you add a getting-started page, mark its blocks and add it to `scripts/e2e-docs.sh`.

## Every page as Markdown

Every page is also published as Markdown at its own address plus `.md`: this page is at `/about/contributing-docs.md`, and the landing page at `/index.md`. The same text is under `/raw/` (which `llms.txt` and `sitemap.md` link to), and `llms-full.txt` is every page's text in one file. The **Copy as Markdown** button beside a page's title copies it; its menu opens it (**View as Markdown**) or copies its address (**Copy Markdown link**). The docs are static files, so the server cannot pick Markdown from a request's `Accept` header: ask for the `.md` address.

The copies are made when the site is built, by the renderer that writes `llms-full.txt`, so a page, its copy and its part of `llms-full.txt` never disagree. After prerendering, `docs-site/modules/markdown-twins.ts` copies each `/raw/` file beside its page's HTML, and `docs-site/public/_headers` serves `.md` files as `text/markdown` on hosts that read it, such as Cloudflare Pages. Before the renderer writes a page, `docs-site/server/utils/markdownTree.ts` escapes text that would read as an HTML tag, such as `\<name\>` in a sentence or `team:<name>` in a table's code, and keeps the backticks of code inside bold text.

```bash [Terminal]
make e2e-docs-twins
```

builds the site and fails when a page has no copy, a copy differs from its `/raw/` file or from its part of `llms-full.txt`, or a copy holds an HTML tag the page does not (only the page's own components, the HTML it writes itself and tables are allowed). With Playwright installed (`npm ci` in `web/`), it then uses the button in a browser, by keyboard alone, in both themes.

When it names a tag such as `<name>`, the page's source has text MDC reads as markup: write it in a code span, or escape it as `\<name\>`.

## Rules

- Every page answers one task. Commands can be copied and run as written, and on the getting-started pages a test does just that.
- Pages about planned features start with a notice saying so.
- Plain words, active voice, sentence-case headings.

The project's internal documents (the plan, ADRs and the build journal) are in `docs/` and are not published here.


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
