# Work on the documentation

The documentation uses Markdown for guides and OpenAPI for the API reference.

## Preview locally

From the repository root, run:

```bash
npx @redocly/cli preview
```

Open [http://localhost:4000](http://localhost:4000). The preview refreshes as you edit files.

## Add a guide

1. Create a Markdown file in `guides/`.
2. Add the page to `sidebars.yaml`.
3. Preview the site and check its links.
4. Commit and push the change.


## Update the API reference

Edit `api/openapi.yaml`, or replace it with the production OpenAPI description. Keep the path in `redocly.yaml` and `sidebars.yaml` in sync if you rename the file.

Run the linter before you push:

```bash
npx @redocly/cli lint api/openapi.yaml
```