# Write a documentation page

Create a page without writing application code.

## Add a page

1. Create `full/content/docs/en/my-guide.md` and write your content in Markdown.
2. Add a `my-guide` entry under `en` in `full/content/docs/pages.json`.
3. Copy an existing entry and change its title, description, category, group, icon and order.
4. Restart or deploy the site. The navigation and search update automatically.

## Page settings

```json
{
    "my-guide": {
        "title": "My guide",
        "description": "What this page explains.",
        "category": "guides",
        "group": "Guides & help",
        "icon": "book",
        "order": 4
    }
}
```

Categories: `start`, `worker`, `desktop`, `analyzer`, `guides`, `changelog`, `reference`. Icons: `home`, `book`, `code`, `document`, `clock`. Add `"draft": true` to hide a page. Nested folders produce nested routes.

## Formatting

| Write                | Result                    |
| -------------------- | ------------------------- |
| `## Heading`         | Section and contents link |
| `**Important**`      | Bold text                 |
| `- Item`             | List                      |
| `[Label](/download)` | Link                      |
| `> Note`             | Note                      |

## Examples and diagrams

Use fenced code blocks with a language such as `json`, `javascript`, `bash`, or `http`. Verify examples against the implementing code. Label shortened responses as excerpts. Never include real API keys, OAuth codes, cookies, or signed download URLs.

Use absolute internal paths such as `/docs/en/reference/jobs`. Write diagrams in fenced `mermaid` blocks. Include `accTitle` and `accDescr` for accessible descriptions, and explain the flow in prose. Diagrams render locally with zoom controls and a source view. Do not use remote rendering URLs or raw HTML.

Use a fenced `visual` block containing `resource-id` or `result-files` for the built-in interactive lessons.

For language tabs, put adjacent code fences in the same group. For example, use `javascript group="download" title="Node.js"` on the first fence and `python group="download" title="Python"` on the next. The original examples remain readable in the raw Markdown.

For a hosted API request, use a fenced `request` block with a JSON object containing `method`, `path`, and an optional `body`. The page generates cURL, JavaScript, Python, Node.js, and PowerShell examples. Paths are relative to `/api/v1`. Set `auth` to `"none"` for a public route or `"session"` for a browser-session route. Session examples only show browser JavaScript. See the [media reference source](/docs-markdown/en/reference/media) for an example.

Indent JSON and code with four spaces. Keep a blank line before and after guard blocks. Use braces for JavaScript `if` statements and explain where an example runs, especially when it uses a private API key.

## Validate and review

From the repository root:

```bash
npm test
npm run lint -w full
npm run build -w full
```

Checks cover documentation metadata, internal links and anchors, diagrams, and JSON examples. Review search, copy actions, mobile navigation, and both themes in a browser too.

Commit Markdown and metadata together after review. Local preview does not publish changes. Follow the normal review and release process before deploying.

The changelog's `public-releases` marker is filled from the public projects listed in the site configuration. It fetches stable release tags and publication dates without authentication and refreshes hourly. Do not add private repositories, credentials, or release bodies to this feed.