`build-docs`

Introduction

Thebuild-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.

Usage

redocly build-docs <api>redocly build-docs <api> --output=custom.htmlredocly build-docs <api> --theme.openapi.disableSearchredocly build-docs <api> --template custom.hbsredocly 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 tothe API section for more details.
--config	string	Path to theconfiguration 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 customHandlebars 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 withRedoc functionality options orRedoc theming options.
--title	string	Set the page title.
--version	boolean	Show version number.

Examples

Specify API

Thebuild-docs command behaves differently depending on how you pass the API to it, and whether theconfiguration file exists.

Pass an API directly

redocly build-docs openapi.yaml

In this case, thebuild-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.

Pass an API alias

Instead of a full path, you can use an API name from theapis object of your Redocly configuration file. For example, with aredocly.yaml configuration file containing the following entry forgames@v1:

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

You can generate a build by including the API name with the command, as shown in the following example:

redocly build-docs games@v1

In this case, after resolving the path behind thegames@v1 name,build-docs generates a build of theapi-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.

Use an alternative configuration file

By default, the CLI tool looks for theRedocly 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

Hide search

The following command uses the optional--theme.openapi argument to build docs with the search box hidden:

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

Use a custom template

The following command builds docs using a custom Handlebars template and adds metadata to the meta tag in the head of the page usingtemplateOptions:

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

Sample custom 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>

Movatterモバイル変換