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

Files

Lorna Jane Mitchell daf030b7a8 Custom plugin documentation (#1222 )

* Remove extra 'resources' landing page, redirect from main one

* Move custom plugins file to its own directory, add redirect to handle

* docs: split the custom plugins page into one page per feature

* docs: extend decorators explanation and link to it from the custom plugins section

* docs: Fix all the links that were broken when I moved things

* Apply excellent suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: Add examples of how to use the custom rule

* docs: Replace the nested visitor example with an object rather than a function

* Update custom-rules.md

minor consistency edits

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: clearer explanation of skip, and finish a broken sentence

* Update docs/custom-plugins/index.md

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* Apply suggestions from code review

Co-authored-by: Adam Altman <adam@redoc.ly>

* docs: use object rather than function for visitor

---------

Co-authored-by: Heather Cloward <heathercloward@gmail.com>
Co-authored-by: Adam Altman <adam@redoc.ly>

2023-08-16 14:26:56 +01:00

5.7 KiB

Raw Blame History

`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 definition filename or alias that you want to generate the build for. Refer to the API examples for more information.
--output, -o	string	Sets the path and name of the output file. The default value is `redoc-static.html`.
--title	string	Sets the page title.
--disableGoogleFont	boolean	Disables Google fonts. The default value is `false`.
--template, -t	string	Uses custom Handlebars templates to render your OpenAPI definition.
--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.
--config	string	Specifies path to the configuration file.
--help	boolean	Shows help.
--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/definition.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>

5.7 KiB Raw Blame History

build-docs