mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 12:47:48 +00:00

Files

dianacheung 4c3d8cf84f docs: update commands documentation (issue 1429) and minor corrections (#1560 )

* docs: updated commands documentation per issue 1429 and minor corrections, ran prettier

* docs: updated commands documentation per issue 1429 and included pr 1560 feedback

* docs: minor formatting and copyedits

---------

Co-authored-by: Diana Cheung <18452752+dianacheung@users.noreply.github.com>
Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>

2024-07-05 20:59:59 +01:00

6.5 KiB

Raw Blame History

`build-docs`

Introduction

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.

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 section for more details.
--config	string	Path to the 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 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 or Redoc theming options.
--title	string	Set the page title.
--version	boolean	Show version number.

Examples

Specify API

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

Pass an API directly

redocly build-docs openapi.yaml

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

Pass an API alias

Instead of a full path, you can use an API name from the apis object of your Redocly configuration file. For example, with a redocly.yaml configuration file containing the following entry for games@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 the games@v1 name, build-docs generates a build of the 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.

Use an alternative 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

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 using templateOptions:

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>

6.5 KiB Raw Blame History

build-docs