{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"build-docs","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["build-docs"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"OpenAPI only"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["build-docs"]}," command currently supports only Swagger 2.0 and OpenAPI 3.0/3.1 descriptions."," ","Support for OpenAPI 3.2 is coming soon."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Redoc 3 migration"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An upcoming Redocly CLI release switches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx @redocly/cli@v1-archive build-docs <api>"]},"."," ","Read ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/blog/redoc-3-whats-new"},"children":["what's new in Redoc 3"]}," for details."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":2},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly build-docs <api>\nredocly build-docs <api> --output=custom.html\nredocly build-docs <api> --theme.openapi.disableSearch\nredocly build-docs <api> --template custom.hbs\nredocly build-docs <api> -t custom.hbs --templateOptions.metaDescription \"Page meta description\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":3},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["api"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path to the API description filename or alias that you want to generate the build for. Refer to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#specify-api"},"children":["the API section"]}," for more details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-an-alternative-configuration-file"},"children":["configuration file"]},". Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," in the local folder."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--disableGoogleFont"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disable Google fonts. The default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--help"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show help."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--lint-config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for the configuration file. Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--output, -o"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set the path and name of the output file. The default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redoc-static.html"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--template, -t"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use custom ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://handlebarsjs.com/"},"children":["Handlebars"]}," templates to render your OpenAPI description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--templateOptions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add template options you want to pass to your custom Handlebars template. To add options, use dot notation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--theme.openapi"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customize your output with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/api-reference-docs/configuration/functionality/"},"children":["Redoc functionality options"]}," or ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/api-reference-docs/configuration/theming/"},"children":["Redoc theming options"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--title"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set the page title."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specify-api","__idx":5},"children":["Specify API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["build-docs"]}," command behaves differently depending on how you pass the API to it, and whether the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-an-alternative-configuration-file"},"children":["configuration file"]}," exists."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"pass-an-api-directly","__idx":6},"children":["Pass an API directly"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly build-docs openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this case, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["build-docs"]}," command builds the API description that was passed to the command."," ","Even if a configuration file exists, the command does not check for APIs listed in it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"pass-an-api-alias","__idx":7},"children":["Pass an API alias"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of a full path, you can use an API name from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," object of your Redocly configuration file."," ","For example, with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration file containing the following entry for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["games@v1"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  games@v1:\n    root: ./openapi/api-description.json\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can generate a build by including the API name with the command, as shown in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly build-docs games@v1\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this case, after resolving the path behind the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["games@v1"]}," name, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["build-docs"]}," generates a build of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-description.json"]}," file."," ","For this approach, the Redocly configuration file is mandatory."," ","Any additional configurations provided in the file are also used by the command."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-an-alternative-configuration-file","__idx":8},"children":["Use an alternative configuration file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the CLI tool looks for the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/configuration"},"children":["Redocly configuration file"]}," in the current working directory."," ","Use the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--config"]}," argument to provide an alternative path to a configuration file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly build-docs --config=./another/directory/config.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hide-search","__idx":9},"children":["Hide search"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following command uses the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--theme.openapi"]}," argument to build docs with the search box hidden:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly build-docs openapi.yaml --theme.openapi.disableSearch\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-a-custom-template","__idx":10},"children":["Use a custom template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following command builds docs using a custom Handlebars template and adds metadata to the meta tag in the head of the page using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["templateOptions"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly build-docs ./openapi/api.yaml -t custom.hbs --templateOptions.metaDescription \"Page meta description\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sample custom Handlebars template:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"handlebars","header":{"controls":{"copy":{}}},"source":"<html lang='en'>\n  <head>\n    <meta charset='utf8' />\n    <title>{{title}}</title>\n    <!-- needed for adaptive design -->\n    <meta description='{{{templateOptions.metaDescription}}}' />\n    <meta name='viewport' content='width=device-width, initial-scale=1' />\n    <style>\n      body {\n        padding: 0;\n        margin: 0;\n      }\n    </style>\n    {{{redocHead}}}\n    {{#unless disableGoogleFont}}<link\n        href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700'\n        rel='stylesheet'\n      />{{/unless}}\n  </head>\n  <body>\n    {{{redocHTML}}}\n  </body>\n</html>\n","lang":"handlebars"},"children":[]}]},"frontmatter":{},"tagList":["admonition"],"title":"build-docs","lastModified":"2026-10-07T06:18:11.000Z"}