mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-06 12:47:48 +00:00
112 lines
5.8 KiB
Markdown
112 lines
5.8 KiB
Markdown
# `build-docs`
|
|
|
|
## Introduction
|
|
|
|
The `build-docs` command builds Redoc into an HTML file.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
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](#api-examples) for more information.<br/> |
|
|
| --config | string | Specifies path to the [configuration file](#custom-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](https://handlebarsjs.com/) 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](https://redocly.com/docs/api-reference-docs/configuration/functionality/) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming/). |
|
|
| --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](#custom-configuration-file)).
|
|
|
|
#### API path to file example
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash Command
|
|
redocly build-docs games@v1
|
|
```
|
|
|
|
```yaml Configuration file
|
|
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](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
|
|
|
|
```bash
|
|
redocly build-docs --config=./another/directory/config.yaml
|
|
```
|
|
|
|
### `theme.openapi` example
|
|
|
|
Build docs with hidden search box:
|
|
|
|
```bash
|
|
redocly build-docs openapi.yaml --theme.openapi.disableSearch
|
|
```
|
|
|
|
### `templateOptions` example
|
|
|
|
Build docs using a custom Handlebars template and add custom `templateOptions`:
|
|
|
|
```bash
|
|
redocly build-docs ./openapi/api.yaml -t custom.hbs --templateOptions.metaDescription "Page meta description"
|
|
```
|
|
|
|
Sample Handlebars template:
|
|
|
|
```handlebars
|
|
<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>
|
|
```
|