redocly build-docs: Static API Reference HTML
redocly build-docs turns an OpenAPI description into a single self-contained Redoc HTML file.
When you publish API reference docs from CI, build-docs produces a static HTML bundle you can upload to any host without a server or build step at deploy time.
What it does
redocly build-docs reads an OpenAPI document and renders it with Redoc into one HTML file with the spec and viewer inlined. It is the CLI equivalent of the hosted Redoc reference page.
Common usage
redocly build-docs openapi.yaml -o dist/index.html
# apply theme options and a page title
redocly build-docs openapi.yaml -o dist/index.html \
--title "Acme API" --theme.openapi.hideDownloadButton=trueOptions
| Flag | What it does |
|---|---|
| -o, --output <file> | Output HTML path (default redoc-static.html) |
| -t, --template <file> | Custom Handlebars template |
| --title <string> | Page <title> |
| --theme.openapi.<key> | Redoc theme/behavior options |
| --config <file> | Path to redocly.yaml |
In CI
Run redocly lint first, then build-docs, then deploy the HTML artifact. Because output is one file, hosting is trivial (GitHub Pages, S3, any static host). Fail the docs job if lint fails so you never publish an invalid spec.
Common errors in CI
"Failed to render ..." usually points at an invalid OpenAPI document; run redocly lint to see the real problem. "ENOENT: no such file or directory, open 'openapi.yaml'" means a wrong path or missing bundle step. An empty or blank page in output typically means the spec has no paths, not a tool error.