feat(cli): render build-docs with Redoc CE 3

.changeset/build-docs-redoc-three.md

@@ -0,0 +1,10 @@
+---
+'@redocly/cli': minor
+---
+
+**Breaking**: Updated the `build-docs` command to Redoc 3 and added support for AsyncAPI descriptions and GraphQL schemas.
+Added the `--openapi`, `--asyncapi`, `--graphql`, and `--inlineBundle` options.
+Removed `--theme.openapi` and `--disableGoogleFont`, pass Redoc options with `--openapi` instead.
+Some Redoc 2 options were renamed or removed, see the [`build-docs` documentation](https://redocly.com/docs/cli/commands/build-docs).
+The command now applies the [decorators](https://redocly.com/docs/cli/decorators) and [preprocessors](https://redocly.com/docs/cli/configuration/reference/preprocessors) from the configuration file.
+Pages built with the `build-docs` command now send [Redoc telemetry](https://redocly.com/docs/redoc/telemetry) from readers' browsers by default.

.claude/skills/redocly-cli/SKILL.md

@@ -31,7 +31,7 @@ Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/c
 | `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        |
+| `build-docs`         | Render an OpenAPI, AsyncAPI, or GraphQL description to an HTML page (Redoc)                                       | Docs rendering        |
 | `preview`            | Local preview of a Redocly project                                                                                | 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       |

CONTRIBUTING.md

@@ -160,13 +160,15 @@ Regenerate it there with `scripts/generate-markdoc-schema.mjs` pointed at this c
 
 ### Update Redoc
 
-When updating Redoc, recompute the subresource integrity [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) (`redocStandaloneSri` in [package.ts](./packages/cli/src/utils/package.ts)):
+The `build-docs` command loads Redoc from the Redocly CDN at the exact `redoc` version in [`packages/cli/package.json`](./packages/cli/package.json).
+When updating Redoc, pin an exact version and check that the CDN serves it:
 
 ```bash
-openssl dgst -sha384 -binary node_modules/redoc/bundles/redoc.standalone.js | openssl base64 -A
+npm install -w packages/cli --save-dev --save-exact redoc@<version>
+curl -I https://cdn.redocly.com/redoc/v<version>/bundles/redoc.standalone.js
 ```
 
-The SRI value also appears in [e2e test snapshots](#e2e-tests) — update those too.
+Then update the [e2e test snapshots](#e2e-tests) and the [smoke test](#smoke-tests) page.
 
 ### Arguments usage
 

docs/@v2/commands/build-docs.md

@@ -5,43 +5,52 @@
 The `build-docs` command builds Redoc into an HTML file that contains your API documentation.
 The standalone HTML file can be easily shared or hosted on a platform of your choice.
 
-{% admonition type="warning" name="OpenAPI only" %}
-The `build-docs` command currently supports only Swagger 2.0 and OpenAPI 3.0/3.1 descriptions.
-Support for OpenAPI 3.2 is coming soon.
-{% /admonition %}
+The command supports Swagger 2.0, OpenAPI 3.0/3.1/3.2, AsyncAPI 2.x/3.x, and GraphQL schemas (`.graphql` or `.gql` files).
+
+The page is rendered with Redoc 3 and loads the Redoc scripts from the Redocly CDN.
+Pass `--inlineBundle` to embed them, so the page works without loading the Redoc scripts from the CDN.
+Only the Redocly logo in the sidebar loads from the CDN.
+
+The page sends [Redoc telemetry](https://redocly.com/docs/redoc/telemetry) from readers' browsers.
+To turn it off, build the page with `REDOCLY_TELEMETRY=off` or with `telemetry: off` in the configuration file.
+
+Redoc options come from the configuration file key that matches the type of your API description: `openapi`, `asyncapi`, or `graphql`.
+The command also applies the [decorators](../decorators.md) and [preprocessors](../configuration/reference/preprocessors.md) from the configuration file.
 
-{% admonition type="warning" name="Redoc 3 migration" %}
-An upcoming Redocly CLI release switches `build-docs` to Redoc 3, and the command prints a notice about it on every run.
-Redoc 3 is faster on large APIs, adds built-in dark mode and support for OpenAPI 3.2, AsyncAPI, GraphQL, and MCP, and is themed with CSS custom properties instead of the Redoc 2 theme object.
-Redoc 2 theme options and custom templates may need updates after the switch.
-To keep the current Redoc 2 output, use Redocly CLI v1: `npx @redocly/cli@v1-archive build-docs <api>`.
+{% admonition type="warning" name="Upgrading from Redoc 2" %}
+Redoc 3 renamed or removed some Redoc 2 configuration options and replaced the Redoc 2 theme object with CSS custom properties.
+When you upgrade, review your Redoc settings against the [Redoc configuration options](https://redocly.com/docs/realm/config/openapi) and check your custom templates.
 Read [what's new in Redoc 3](https://redocly.com/blog/redoc-3-whats-new) for details.
+To keep the Redoc 2 output, use Redocly CLI v1: `npx @redocly/cli@v1-archive build-docs <api>`.
 {% /admonition %}
 
 ## Usage
 
 ```bash
 redocly build-docs <api>
 redocly build-docs <api> --output=custom.html
-redocly build-docs <api> --theme.openapi.disableSearch
+redocly build-docs <api> --inlineBundle
+redocly build-docs <api> --openapi.hideDownloadButtons
 redocly build-docs <api> --template custom.hbs
 redocly build-docs <api> -t custom.hbs --templateOptions.metaDescription "Page meta description"
 ```
 
 ## Options
 
-| Option              | Type    | Description                                                                                                                                                                                                                        |
-| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| api                 | string  | Path to the API description filename or alias that you want to generate the build for. Refer to [the API section](#specify-api) for more details.                                                                                  |
-| --config            | string  | Path to the [configuration file](#use-an-alternative-configuration-file). Defaults to `redocly.yaml` in the local folder.                                                                                                          |
-| --disableGoogleFont | boolean | Disable Google fonts. The default value is `false`.                                                                                                                                                                                |
-| --help              | boolean | Show help.                                                                                                                                                                                                                         |
-| --lint-config       | string  | Specify the severity level for the configuration file. Possible values: `warn`, `error`, `off`. Default value is `warn`.                                                                                                           |
-| --output, -o        | string  | Set the path and name of the output file. The default value is `redoc-static.html`.                                                                                                                                                |
-| --template, -t      | string  | Use custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI description.                                                                                                                                   |
-| --templateOptions   | string  | Add template options you want to pass to your custom Handlebars template. To add options, use dot notation.                                                                                                                        |
-| --theme.openapi     | string  | Customize your output with [Redoc functionality options](https://redocly.com/docs/api-reference-docs/configuration/functionality/) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming/). |
-| --title             | string  | Set the page title.                                                                                                                                                                                                                |
+| Option            | Type    | Description                                                                                                                                                         |
+| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| api               | string  | Path to the API description filename or alias that you want to generate the build for. Refer to [the API section](#specify-api) for more details.                   |
+| --asyncapi        | string  | Customize your output with [Redoc AsyncAPI options](https://redocly.com/docs/realm/config/asyncapi). Use dot notation, for example `--asyncapi.jsonSamplesDepth 4`. |
+| --config          | string  | Path to the [configuration file](#use-an-alternative-configuration-file). Defaults to `redocly.yaml` in the local folder.                                           |
+| --graphql         | string  | Customize your output with [Redoc GraphQL options](https://redocly.com/docs/realm/config/graphql). Use dot notation, for example `--graphql.showBuiltInScalars`.    |
+| --help            | boolean | Show help.                                                                                                                                                          |
+| --inlineBundle    | boolean | Embed the Redoc scripts into the output file instead of loading them from the Redocly CDN. The default value is `false`.                                            |
+| --lint-config     | string  | Specify the severity level for the configuration file. Possible values: `warn`, `error`, `off`. Default value is `warn`.                                            |
+| --openapi         | string  | Customize your output with [Redoc OpenAPI options](https://redocly.com/docs/realm/config/openapi). Use dot notation, for example `--openapi.hideDownloadButtons`.   |
+| --output, -o      | string  | Set the path and name of the output file. The default value is `redoc-static.html`.                                                                                 |
+| --template, -t    | string  | Use custom [Handlebars](https://handlebarsjs.com/) templates to render your API description.                                                                        |
+| --templateOptions | string  | Add template options you want to pass to your custom Handlebars template. To add options, use dot notation.                                                         |
+| --title           | string  | Set the page title.                                                                                                                                                 |
 
 ## Examples
 
@@ -88,12 +97,23 @@ Use the optional `--config` argument to provide an alternative path to a configu
 redocly build-docs --config=./another/directory/config.yaml
 ```
 
-### Hide search
+### Configure Redoc
+
+Each API description type reads its options from its own configuration file key, so one file can configure all three:
+
+```yaml Configuration file
+openapi:
+  hideDownloadButtons: true
+asyncapi:
+  jsonSamplesDepth: 4
+graphql:
+  showBuiltInScalars: true
+```
 
-The following command uses the optional `--theme.openapi` argument to build docs with the search box hidden:
+The matching command-line argument replaces the options from the configuration file:
 
 ```bash
-redocly build-docs openapi.yaml --theme.openapi.disableSearch
+redocly build-docs openapi.yaml --openapi.hideDownloadButtons
 ```
 
 ### Use a custom template
@@ -121,10 +141,6 @@ Sample custom Handlebars template:
       }
     </style>
     {{{redocHead}}}
-    {{#unless disableGoogleFont}}<link
-        href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700'
-        rel='stylesheet'
-      />{{/unless}}
   </head>
   <body>
     {{{redocHTML}}}

docs/@v2/guides/migrate-from-redoc-cli.md

@@ -40,23 +40,22 @@ Details and examples of using `bundle` are on the [`bundle` command page](../com
 
 Some of the configuration options have been updated. This section shows how to check which of your settings should be changed.
 
-### Renamed fields
+### Update renamed and removed options
 
-Two of the configuration settings were renamed for consistency with the rest of the Redocly tools.
+The `build-docs` command renders the docs with Redoc 3, which renamed or removed some Redoc 2 options.
+Check the options you use against the [Redoc migration guide](https://redocly.com/docs/redoc/config-migration).
 
-- Replace `menu` with `sidebar`
-- Replace `codeSample` with `codeBlock`
-
-In both cases, the child options should work as before.
+One of the removed options is `theme`, so `theme.*` settings have no effect.
+Customize the appearance with [CSS variables](https://redocly.com/docs/redoc/deployment/html#theme-configuration) in a `<style>` tag of a [custom template](../commands/build-docs.md#use-a-custom-template) instead.
 
 ### Update command-line configuration
 
-Replace your existing `--options.theme.*` settings with a new prefix: `--theme.openapi.theme.*`.
+Replace the `--options.*` prefix with `--openapi.*`.
 
-For example if you used `redoc-cli build --options.theme.sidebar.width='300px' openapi.yaml` then the new command would be:
+For example if you used `redoc-cli build openapi.yaml --options.hideSchemaTitles` then the new command would be:
 
 ```sh
-redocly build-docs --theme.openapi.theme.sidebar.width='300px' openapi.yaml
+redocly build-docs openapi.yaml --openapi.hideSchemaTitles
 ```
 
 ### Update configuration file
@@ -65,14 +64,11 @@ Configuration belongs in a file named `redocly.yaml`, or in a file name specifie
 
 Re-name options that begin with `features.openapi.*` to `openapi.*`.
 Do this either at the top level of the configuration, or per API.
-A configuration file to change one of the colours to a rather lurid purple would look something like the following example:
+The following configuration file hides schema titles:
 
 ```yaml
 openapi:
-  theme:
-    colors:
-      primary:
-        main: '#ff00ff'
+  hideSchemaTitles: true
 ```
 
 Define the base customization; older versions of the tools defaulted to using `recommended`, but this is no longer assumed. Set it in `redocly.yaml` like this:

docs/@v2/guides/migrate-to-v2.md

@@ -170,6 +170,27 @@ This update changes how some YAML features are interpreted compared to v1.x:
   baz: something else
   ```
 
+### Changes in the `build-docs` command
+
+The [`build-docs`](../commands/build-docs.md) command renders documentation with Redoc 3 instead of Redoc 2.
+Redoc options come from the configuration key that matches your API description type: `openapi`, `asyncapi`, or `graphql`.
+The `--theme.openapi` option has been removed:
+
+```bash
+# ❌ Removed
+redocly build-docs openapi.yaml --theme.openapi.hideDownloadButtons
+
+# ✅ Use this instead
+redocly build-docs openapi.yaml --openapi.hideDownloadButtons
+```
+
+The `--disableGoogleFont` option has been removed too, because Redoc 3 pages load no Google Fonts.
+
+Redoc 3 renamed or removed some Redoc 2 options and replaced the theme object with CSS custom properties, so review your settings against the [Redoc configuration options](https://redocly.com/docs/realm/config/openapi) and check your custom templates.
+Read [what's new in Redoc 3](https://redocly.com/blog/redoc-3-whats-new) for details.
+
+To keep the Redoc 2 output, pin `@redocly/cli` to the version you used before, or use Redocly CLI v1: `npx @redocly/cli@v1-archive build-docs openapi.yaml`.
+
 ### Platform changes
 
 - **Legacy Registry**: Support for the legacy Redocly API Registry has been removed in favor of [Redocly platform](https://app.cloud.redocly.com/).
@@ -228,6 +249,7 @@ paths:
 1. **Replace `undefined` assertions** with `defined: true`.
 1. **Revise `join` command usage** if your workflow relies on root-level `servers` in joined output.
 1. **Revise your YAML files** to comply with the latest YAML specification (v1.2).
+1. **Revise `build-docs` usage**: replace `--theme.openapi` with `--openapi`, remove `--disableGoogleFont`, review your Redoc options and custom templates for Redoc 3, or pin the CLI version to keep the Redoc 2 output.
 1. **Update configuration structure**:
    - Replace `apiDefinitions` with `apis`
    - Move `features.openapi.*` to `openapi.*`

docs/@v2/usage-data.md

@@ -33,6 +33,7 @@ Values such as file names, organization IDs, and URLs are removed, replaced by j
 ## Opt out of data collection
 
 To opt out, set the `REDOCLY_TELEMETRY` environment variable to `off`, or set `telemetry: off` in the `redocly.yaml` configuration file.
+This also turns off Redoc telemetry in pages that you build with [`build-docs`](./commands/build-docs.md).
 
 ## Requests to the Redocly platform