Redocly

View saved version →

---
name: recheck-config
description: Use when you create or tune the recheck block and recheck/* presets in redocly.yaml for a project — choose presets, set severities from measured counts, add exceptions, adopt a baseline, and validate the result.
---

# Configure recheck in redocly.yaml

Configure `redocly recheck` for a project the way its maintainers would: measure first, decide per rule, and record intent.
The documentation is at [redocly.com/docs/cli/recheck](https://redocly.com/docs/cli/recheck); favor it over memory for rule names and options.

## How the configuration is shaped

Presets go in the root `extends`.
Adjustments go in the `recheck` block, with rules nested under `rules`.
The `lint` command ignores both, so they live next to the API ruleset:

```yaml
extends:
  - recommended
  - recheck/markdown
  - recheck/prose
recheck:
  excludes:
    - CHANGELOG.md
  rules:
    recheck/line-length: off
    recheck/no-duplicate-heading:
      severity: warn
      assertions:
        no-duplicate-heading:
          siblingsOnly: true
```

Rules of the shape:

- A rule key is `<namespace>/<name>`: `recheck/line-length`, `google/no-via`, or your own, such as `acme/product-names`.
- A severity string (`off`, `info`, `warn`, `error`) adjusts a rule that a preset defines.
  For a key no preset defines, it is a configuration error, because the rule has no assertions.
- A rule object merges over the preset's rule, but its `assertions` merge by assertion id: one option you set on a `swap` or `pattern` assertion replaces the preset's whole word list.
  To reject one term from a preset's list, turn the rule off, restate the full list, or use an inline directive.
- A new prose rule needs `severity`, `message`, and `assertions`.
  A new Markdown rule, such as `recheck/list-length`, needs only `severity` and `assertions`.
- The block does not accept `extends` or `baseline`; both are configuration errors.
- The command reads the root block only.
  A `recheck` block under `apis.<name>` does nothing and prints a warning.

## Start a new config

1. Begin with the structural preset, and run recheck to validate it:

   ```yaml
   extends:
     - recheck/markdown
   ```

   ```bash
   npx @redocly/cli recheck docs
   npx @redocly/cli check-config
   ```

   The `recheck` command reports configuration errors before it lints anything, and `check-config` validates the block's shape.

2. Add prose presets deliberately, not wholesale.
   `recheck/prose` is a small starter at `warn`.
   `recheck/google` and `recheck/microsoft` are large style guides, detection-only, that need tuning before they help.
   `recheck/plain-language`, `recheck/inclusive-language`, and `recheck/technical-english` compose onto either.

3. If the project writes Markdoc tags, add `recheck/markdoc` to `extends` and `markdoc: true` to the block.
   Without the flag, the Markdoc rules never report.

## Tune severities from measurements, not taste

1. Run the whole document set and count findings per rule:

   ```bash
   npx @redocly/cli recheck docs --summary=json --summary-path=recheck-summary.json
   ```

   The summary's `breakdown` has the count per rule and severity.
   For examples of each rule's findings, run `--rule=<name>` and read a few.

2. Decide per rule from the counts:
   - `error` — enforce now; the document set is clean or you fix it in the same change.
   - `warn` — a worklist; visible, not blocking.
   - `off` — decided against; keep a YAML comment that says why, or the decision is lost.

3. Prefer fixing content over configuring around it.
   Run `--fix` first; most structural findings repair themselves.
   Review the fix list before you commit: fixes that re-indent lines can move content out of an indented Markdoc tag body.

## Exceptions, in order of preference

1. Fix the content.
2. The top-level `excludes` list, or a rule's `excludes` or `appliesTo`, for generated or frozen content such as archives and vendored docs — with a comment naming the reason.

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: recheck-lint
description: Use when you write or edit Markdown in a project whose redocly.yaml has a recheck block or a recheck/* preset in extends — run redocly recheck on the touched files before you commit them or hand them over, and fix what it finds.
---

# Lint Markdown with recheck before you commit it

This project lints Markdown structure and prose with `redocly recheck`.
Your Markdown must pass it, the same as code must pass its tests.

## When this applies

Look for a `redocly.yaml` in the project root or above the files you touched.
This skill applies when that file has a `recheck` block, or a `recheck/*` preset in its root `extends`, for example:

```yaml
extends:
  - recommended
  - recheck/markdown
recheck:
  rules:
    recheck/line-length: off
```

If neither exists, skip this skill.
The command checks nothing in that case and says so.

## What to do

1. After you write or edit Markdown files, run recheck on them:

   ```bash
   npx @redocly/cli recheck <file-or-directory>
   ```

   Pass the files you touched, not the whole repository, so the report is yours to act on.

2. If it reports errors, run the auto-fix first — most structural findings repair themselves:

   ```bash
   npx @redocly/cli recheck <file-or-directory> --fix
   ```

   The command lists every edit it made.
   Read the list: a fix inside a Markdoc tag body or a code sample deserves a look.

3. Fix the remaining errors by hand.
   Read each message; the rule name links the finding to its intent.
   To see one rule at a time, add `--rule=<name>` with the name the report prints.

4. Re-run until it reports no errors, and only then commit or output the content.
   The command exits with code 1 while errors remain.

## Rules of conduct

- Fix content instead of suppressing findings.
  Suppress only a true positive that must stay as written, with an inline directive on that one line:

  ```markdown
  <!-- recheck-disable-next-line recheck/rule-name -->
  ```

  Name the rule by its full key or by the short name the report prints.
  Never disable a rule project-wide to make your change pass, and never edit the `recheck` block to get past a finding.

- Warnings and info findings do not block you.
  Leave them unless the task asks for cleanup.
- If a `.redocly.recheck-baseline.yaml` file sits next to `redocly.yaml`, the baseline already covers old findings; only new findings are yours to fix.
  Do not run `--generate-baseline` to absorb findings your change introduced.
  If your change removed old findings, the run reports stale baseline entries; regenerate the baseline then, and commit the smaller file with your change.
- A finding you believe is a false positive is worth reporting to the maintainer, not silently suppressing.
- Do not add `markdownlint` or `vale` comments.
  Recheck does not read them.

View saved version →

---
name: redocly
description: >-
  Set up, write, preview, and publish documentation with Redocly, and work on existing Redocly projects.
  Use when the user wants to set up Redocly in a repository, create a docs site, document an API from an OpenAPI, AsyncAPI, or GraphQL description, preview docs locally, publish through Reunite, clone a Redocly-hosted project, or run Redocly CLI.
  Also use when editing a project with redocly.yaml, sidebars.yaml, or a @theme folder, and when unsure which Redocly skill applies.
---

# Redocly

Redocly makes the tools for API documentation and developer portals.

## Redocly products

- **Realm** is the engine.
  It converts a folder of content into the site: Markdown pages, API descriptions (OpenAPI, AsyncAPI, GraphQL, SOAP) that become API reference docs, and React pages.
  The file path of a content file is its URL.
  `redocly.yaml` holds the site settings, `sidebars.yaml` the navigation, and `@theme/` the custom styles and components.
  None of them is required.
- **Reunite** is the cloud platform.
  It hosts the project's Git repository, or connects to one on GitHub, GitLab, Bitbucket, or Azure DevOps.
  It builds a preview for every pull request, publishes the production branch, and provides the browser editor, access control, and analytics.
- **Redocly CLI** is the open-source command-line tool, run as `npx @redocly/cli` (or `redocly` after `npm i -g @redocly/cli`).

| Command | Use |
| --- | --- |
| `preview` | Serve the project locally with live reload, the default way to start a project |
| `check-config` | Validate `redocly.yaml` and name unknown keys |
| `lint`, `bundle`, `split`, `join` | Validate, merge, and restructure OpenAPI, AsyncAPI, and Arazzo descriptions |
| `recheck` | Lint Markdown structure, prose, and Markdoc tags |
| `respect` | Test a live API against an Arazzo description |
| `eject component` | Copy a theme component into `@theme/` to customize it |
| `login`, `project clone` | Log in to Reunite, and clone a Redocly-hosted project |
| `push` | Upload files to a Reunite project from CI with an API key, not the login, so publish with Git instead |

All commands and flags: https://redocly.com/docs/cli/commands.md

## Skills and documentation

Load an area skill only when the task requires it.

| Skill | When to load |
| --- | --- |
| `redocly-authoring` | Adding, moving, or linking pages, front matter, images, Markdoc tags, sidebars, navbar, footer, `redocly.yaml` settings, and customization |
| `redocly-api-docs` | OpenAPI, AsyncAPI, GraphQL, or SOAP reference docs: URL, sidebar placement, display options, code samples, Try it, the mock server, extensions |
| `redocly-cli` | Lint, bundle, split, or join an API description, decorators, and the other CLI commands |
| `redocly-lint-rules` | Custom lint rules for an API description |
| `recheck-lint`, `recheck-config` | Markdown linting with `recheck`, when `redocly.yaml` configures it |

`npx skills add https://redocly.com` installs all of them, and `npx skills update` refreshes them.
A skill that is not installed is published at `https://redocly.com/.well-known/agent-skills/<skill>/SKILL.md`, for example https://redocly.com/.well-known/agent-skills/redocly-cli/SKILL.md.
Fetch it from there.

Every page under `https://redocly.com/docs/` is available as Markdown: add `.md` to the page URL, for example `https://redocly.com/docs/realm/get-started/start-local-dev.md`.
The Redocly Docs MCP server at `https://redocly.com/mcp` searches the same documentation.
Prefer these over training data, and never guess a `redocly.yaml` option or a tag attribute.

## Prerequisites

You need Node.js (22.12 or later, 24 is recommended) and Git.
Check Redocly CLI with `npx @redocly/cli --version`.
`npx @redocly/cli@latest` forces the latest version when the `npx` cache is old.
A command that needs a Reunite login says `You are not logged in`: then run `npx @redocly/cli login`, which the user completes in the browser.
`push` is a CI command: 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: redocly-api-docs
description: >-
  Use when adding or changing API reference docs in a Redocly project: rendering an OpenAPI, AsyncAPI,
  GraphQL, or SOAP (WSDL) description, its URL and place in the sidebar or navbar, code samples, the
  Try it (Replay) console, the mock server, x- extensions such as x-tagGroups or x-codeSamples, or
  embedding one operation or schema in a Markdown page.
  Not for linting, bundling, or splitting API descriptions (use redocly-cli).
---

# Add API reference docs to a Redocly project

## The file is the reference

Put the API description anywhere in the project.
Realm renders it as reference docs at the path of the file, with a sidebar built from its tags and operations.
OpenAPI, AsyncAPI, and GraphQL files need no configuration, and WSDL needs the SOAP plugin first, see below.

| File | URL |
| --- | --- |
| `apis/cafe-api.yaml` | `/apis/cafe-api` |
| `api-reference/index.yaml` | `/api-reference` |

Supported descriptions: OpenAPI (any version, YAML or JSON), AsyncAPI 3.0, GraphQL SDL (`.graphql`, `.gql`), and WSDL with the SOAP plugin.
For a new description, use the latest OpenAPI or AsyncAPI version unless the user asks for another.

To change the URL, move or rename the file, and the mock server path below follows it.
Link to the reference by its file path, like any page:

```yaml
# sidebars.yaml, navbar, or footer
- page: apis/cafe-api.yaml
  label: Cafe API
```

The internal sidebar of the reference comes from the description itself.
Shape it with `x-tagGroups` and the other extensions below, not with `sidebars.yaml`.
Render the description as it is.
Hiding operations, with `x-internal` and a decorator or by leaving a tag out of `x-tagGroups`, and reformatting the file are the user's decisions, so ask first.

Full reference: https://redocly.com/docs/realm/content/api-docs/add-openapi-docs.md

## AsyncAPI, GraphQL, and SOAP

- AsyncAPI 3.0 files render like OpenAPI files, with `asyncapi` options and their own extensions: https://redocly.com/docs/realm/content/api-docs/add-asyncapi-docs.md
- GraphQL SDL files get a sidebar from their queries, mutations, and types, and `graphql.menu` groups them: https://redocly.com/docs/realm/content/api-docs/add-graphql-docs.md
- SOAP needs `@redocly/portal-plugin-soap-api` and `@redocly/realm` in `package.json`, `plugins: ['@redocly/portal-plugin-soap-api/plugin.js']` in `redocly.yaml`, and `.wsdl` files: https://redocly.com/docs/realm/content/api-docs/add-soap-docs.md

## OpenAPI display options

Options go under the top-level `openapi` key of `redocly.yaml` for every API, or under `apis.<name>.openapi` for one API.
Both merge, and the per-API value wins.
With one API, the top-level key is enough.
Use the per-API form for a setting that must not apply to APIs added later.
`asyncapi` and `graphql` work the same way.

```yaml
openapi:
  layout: stacked
  hideReplay: true
  codeSamples:
    languages:
      - lang: curl
      - lang: Python
apis:
  cafe_api:
    root: apis/cafe-api.yaml
    openapi:
      hideReplay: false
```

| Option | Default | Effect |
| --- | --- | --- |
| `layout` | `three-panel` | `stacked` moves the samples into the middle panel |
| `hideReplay` | `false` | Hide the Try it buttons |
| `codeSamples.languages` | a default set | Which generated samples to show, in order, by `lang` (`curl`, `JavaScript`, `Python`, ...), and `label` renames a tab. Supported values: https://redocly.com/docs/realm/config/openapi/code-samples.md |
| `hideDownloadButtons` | `false` | Hide the download links, which does not hide the description |
| `downloadUrls` | - | Download links: a list of `title` and `url` |
| `schemaDefinitionsTagName` | - | List all schemas in a sidebar section with this name |
| `showExtensions` | `false` | Show `x-` fields in the docs |
| `sortRequiredPropsFirst` | `false` | Required properties first |
| `excludeFromSearch` | `false` | Keep the API out of search and `llms.txt` |

All options: https://redocly.com/docs/realm

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: redocly-authoring
description: >-
  Use when writing or changing content in a Redocly project: adding, moving, or renaming pages, choosing
  file names and URLs, links and images, page titles and front matter, Markdoc tags such as admonitions,
  tabs, cards, code groups, and partials, the sidebar, navbar, and footer, or site settings in redocly.yaml.
  Not for API reference docs from OpenAPI, AsyncAPI, or GraphQL files (use redocly-api-docs).
---

# Write content for a Redocly project

## The folder is the site

Realm builds the site from the project folder.
Every content file is a page, and the path of the file is the URL of the page:

| File | URL |
| --- | --- |
| `index.md` | `/` |
| `guides/quickstart.md` | `/guides/quickstart` |
| `guides/index.md` | `/guides` |
| `apis/cafe-api.yaml` | `/apis/cafe-api` (API reference, see `redocly-api-docs`) |
| `changelog.page.tsx` | `/changelog` (React page) |

A file named `index` is the page of its folder.
To change a URL, move or rename the file, and add the old URL to `redirects` in `redocly.yaml` when the page was published.

Some folders are not pages.
`_partials/` (by default) holds reusable content, and files in `static/` are copied to the site root as they are: `static/robots.txt` is served at `/robots.txt`.
Realm reserves `@theme/` (customizations), `@l10n/` (translations), `@api/`, and `@skills/`.
Any other folder that starts with `@` is a content version.
Two files that resolve to the same URL, such as `payments.md` and `payments/index.md`, get numbered URLs, so avoid them.

Full reference: https://redocly.com/docs/realm/content/project-structure.md

## Before you write

Read `redocly.yaml` and the nearest `sidebars.yaml` when they exist, as a project can have neither.
Read two or three pages next to the one you add and match their file naming, heading style, and image location.
Default to kebab-case file names when the folder has no pattern.
Search for existing content before you add a page: the right change may be a new section or a link.

## Pages

A page is Markdown with optional YAML front matter.
The first H1 is the page title.
Front matter holds the settings of one page, such as a search title that differs from the H1 or a description.
Omit it when the defaults do:

```markdown
---
seo:
  title: Rate limits for the Acme API
  description: Request limits, the 429 response, and how to retry.
---

# Rate limits
```

`slug: /custom-url` serves the page at a different URL.
Use it only when the author wants the file to stay where it is.
The other page settings, such as `rbac`, `markdown.toc`, `feedback`, or `navbar.hide`, are in the front matter reference: https://redocly.com/docs/realm/config/front-matter-config.md

## Links and images

Link to files, with their extension, relative to the page: `[Quickstart](./quickstart.md)`, `[Cafe API](../apis/cafe-api.yaml)`, `[Install](../setup/index.md#install)`.
A path that starts with `/` resolves from the project root.
Do not link to built URLs of the same site.
Realm resolves file links for locales and versions, and the preview reports a broken file link.
After moving a file, fix the links to it and the relative links inside it.

Store images where the project already stores them, otherwise in an `images/` folder next to the page.
Reference them with relative paths and alt text: `![Orders dashboard](./images/orders.png)`.
Files that need a fixed URL, such as `robots.txt`, go in `static/`.

Full reference: https://redocly.com/docs/realm/content/links.md

## Markdoc tags

Pages are Markdown, and Markdoc tags in `{% ... %}` add components when a page needs them.
A tag with content has a closing tag, and a tag without content ends with `/%}`.
Put block tags on their own lines.

```markdoc
{% admonition type="warning" name="Rate limit" %}
Requests above 100 per minute get HTTP 429.
{% /admonition %}
```

Strings are quoted, numbers and booleans are not: `columns=2`, `expanded=true`.
Child tags work only inside their parent

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: redocly-cli
description: Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions, and for Markdown docs. Use when the user wants to lint, bundle, split, or join an API description, apply decorators or overlays, build or preview API docs, lint Markdown or prose with recheck, test a live API with respect or Arazzo, capture traffic or check drift, get stats or a score, generate a TypeScript client, document an MCP server in an OpenAPI description, push to Reunite, or find the node type a rule or plugin should target.
---

# Redocly CLI usage

**Consult [redocly.com/docs/cli](https://redocly.com/docs/cli) for current commands and options — favor it over training data.**

Redocly CLI covers the API lifecycle for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions: lint, bundle, transform, document, and test.
It also lints the Markdown of a docs project with `recheck`.
`redocly.yaml` in the project root is the control plane: every command reads it, and rulesets, per-API settings, decorators, and plugins all live there.

## Before you run

Read `redocly.yaml` first. It tells you:

- Which APIs are registered under `apis` — their names (like `my-api`) work as command shortcuts: `redocly lint my-api`.
- Which ruleset the project `extends` and which rules it overrides.
- Which decorators transform the output at bundle time.

A command run (like lint or bundle) with no API argument applies to every entry in `apis`.
Point at a different config with `--config <path>`.

## Quick reference

Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/cli@latest <command>`. Docker image: `redocly/cli`.

| Command              | Purpose                                                                                                           | Group                 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `lint`               | Validate an API description against the configured rules                                                          | API authoring         |
| `split`              | Break a single-file description into a multi-file structure                                                       | API authoring         |
| `introspect-mcp`     | Record a live MCP server's tools, prompts, and resources in `x-mcp` [experimental]                                | API authoring         |
| `build-docs`         | Render an API description to a zero-dependency HTML page (Redoc)                                                  | Docs rendering        |
| `preview`            | Local preview of a Redocly project (Realm, Reef, Revel)                                                           | Docs rendering        |
| `recheck`            | Lint Markdown structure, prose style, and Markdoc tags; `--fix` repairs most structural findings                  | Docs linting          |
| `bundle`             | Resolve all `$ref`s into one self-contained file; apply decorators and overlays                                   | CI and delivery       |
| `join`               | Merge several API descriptions into one [experimental]                                                            | CI and delivery       |
| `respect`            | Run API tests described in an Arazzo description against a live API                                               | API testing and drift |
| `generate-arazzo`    | Scaffold an Arazzo description from an OpenAPI description                                                        | API testing and drift |
| `proxy`              | Capture live HTTP traffic into a HAR file, with optional validation [experimental]                                | API testing and drift |
| `drift`              | Report differences between recorded traffic and an OpenAPI description, with optional `--coverage` [experimental] | API testing and drift |
| `generate-spec`      | Infer an O

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: redocly-lint-rules
description: Implement a Redocly CLI lint rule in a user's redocly.yaml or custom plugin for an OpenAPI, AsyncAPI, or Arazzo description. Use when the user wants a convention enforced, asks for a configurable rule or a plugin rule, debugs a rule that never reports or gives false positives, or migrates rules from another linter such as Spectral.
---

# Implementing a Redocly CLI lint rule

Turn a check written in plain language ("every array schema must declare `items`") into a Redocly lint rule that works and is tested.

**The ladder.** Redocly gives three ways to do a check. The first is the cheapest to maintain.

1. **Built-in rule** — one of the [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) does the check.
2. **Configurable rule** — one or more `rule/*` entries in `redocly.yaml` do the check with assertions.
3. **Custom plugin** — JavaScript code that implements your own rule with the visitor pattern. Use this rung last.

Do the checks one at a time.
Start each check at rung 1.
Go down one rung only when the current rung cannot do the check.
Take all syntax from the [official docs](https://redocly.com/docs/cli/) or the [cookbook](https://github.com/Redocly/redocly-cli/tree/main/cookbook).
Trust the docs, not your memory.
Use modern syntax, such as ESM instead of CommonJS. If the project has its own style, follow the project.

## 1. Triage

For each check, write down three things: the node it looks at, what must be true, and what a violation looks like.
Triage each check on its own. Different checks can land on different rungs.

Get node names from the `inspect-node-types` command, not from memory.
The type tree is different in each specification and each version.
The names it prints are the `subject.type` of a configurable rule, and the visitor keys of a plugin.

| to learn                              | run                             |
| ------------------------------------- | ------------------------------- |
| the type at one location              | `--pointer='#/paths/~1orders'`  |
| every node, or every node of one type | no flag, or `--type=Schema`     |
| which types the description uses      | `--summary`                     |
| **where a type can sit**              | `--type=<Type> --parents`       |
| the ancestors of one node             | `--pointer=<pointer> --parents` |

The last two rows give a rule its scope.
When a type sits below more than one parent, the rule needs a `where` gate.
Without that gate, the rule also reports the branches you do not want.
The command shows the description in front of you. It does not show everything the specification permits.
When the command does not print a branch, that branch is unproven. It is not absent.
The command does not shorten step 3. It gives you type names. It does not tell you whether your assertions express the check.

Walk the ladder for each check:

- Search the [built-in rules list](https://redocly.com/docs/cli/rules/built-in-rules) for the concept.
  A trailing slash in a path gives `no-path-trailing-slash`.
  When the config already extends a ruleset that turns the built-in on, tell the user. Do not add the rule again.
  **Use the built-in when its description matches the check, even when it reports more than the rule you replace.**
  A built-in is usually a better version of the same idea, so its extra findings are the check done correctly.
  When you write the narrower behavior by hand, you exchange a maintained rule for code that you must maintain.
  Go down one rung only when the built-in checks something different.
  Report which built-in you took, and what it adds.
- Make sure the built-in supports the spec versions that the project lints.
  Some built-ins support one version only.
  `no-invalid-media-type-examples` supports OpenAPI 3.x, so it leaves a Swagger 2.0 check unenforced.
  Redocly prints `Unused rules found in redocly.yaml` when an enabled rule cannot apply to a document.
  Correct that li

Preview of the first 4,000 characters. Read full instructions →