`build-docs`

Introduction

The build-docs command builds Redoc into an HTML file.

Usage

redocly build-docs <api>
redocly build-docs <api> --output=custom.html
redocly build-docs <api> --theme.openapi.disableSearch
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 examples for more information.
--config	string	Specifies path to the configuration file.
--disableGoogleFont	boolean	Disables Google fonts. The default value is false.
--help	boolean	Shows help.
--lint-config	string	Specify the severity level for the configuration file. Possible values: warn, error, off. Default value is warn
--output, -o	string	Sets the path and name of the output file. The default value is redoc-static.html.
--template, -t	string	Uses custom Handlebars templates to render your OpenAPI description.
--templateOptions	string	Adds template options you want to pass to your custom Handlebars template. To add options, use dot notation.
--theme.openapi	string	Customizes your output with Redoc functionality options or Redoc theming options.
--title	string	Sets the page title.
--version	boolean	Shows version number.

Examples

API examples

The command accepts an API positional argument as either a file (no configuration file is required) or an alias (requires a configuration file).

API path to file example

redocly build-docs openapi.yaml

In this case, the build-docs command builds the API at the path provided. The configuration file is ignored.

API alias example

Instead of a full path, you can use an API name from the apis object of your Redocly configuration file.

redocly build-docs games@v1

apis:
  games@v1:
    root: ./openapi/api-description.json

The build-docs command uses any additional configurations provided in the file.

Custom configuration file

By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional --config argument to provide an alternative path to a configuration file.

redocly build-docs --config=./another/directory/config.yaml

`theme.openapi` example

Build docs with hidden search box:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

`templateOptions` example

Build docs using a custom Handlebars template and add custom templateOptions:

redocly build-docs ./openapi/api.yaml -t custom.hbs --templateOptions.metaDescription "Page meta description"

Sample Handlebars template:

<html>
  <head>
    <meta charset='utf8' />
    <title>{{title}}</title>
    <!-- needed for adaptive design -->
    <meta description='{{{templateOptions.metaDescription}}}' />
    <meta name='viewport' content='width=device-width, initial-scale=1' />
    <style>
      body { padding: 0; margin: 0; }
    </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}}}
  </body>
</html>

build-docs