docs: add cli config reference (#1483)

* docs: Add resolve config reference

* docs: Start API reference, needs child config entries

* docs: Add sidebar entries for config reference pages

* docs: Add rules and decorators config pages

* docs: Fix links and format

* docs: Fix links and formatting

* docs: Add extends and plugins config reference pages

* docs: Add a basic preprocessor page

* docs: Update from review feedback

* Apply suggestions from code review

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

* docs: Reformat required labels

* Apply suggestions from code review

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

* docs: Fix misspelling

---------

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

docs/configuration/index.md

@@ -213,7 +213,7 @@ Redocly CLI supports one `http` header per URL.
 
 Here is an example for adding header definitions:
 
-```yaml
+```text
 resolve:
   http:
     headers:

docs/configuration/reference/apis.md

@@ -0,0 +1,85 @@
+# `apis`
+
+## Introduction
+
+If your project contains multiple APIs, the `apis` configuration section allows you to set up different rules and settings for different APIs.
+
+## Options
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- `{name}@{version}`
+- [API object](#api-object)
+- **REQUIRED**. Each API needs a name and optionally a version. Supports alphanumeric characters and underscores.
+
+{% /table %}
+
+### API object
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- root
+- string
+- **REQUIRED**. Path to the root API description file.
+
+---
+
+- rules
+- [Rules object](./rules.md)
+- Additional rule configuration for this API.
+
+---
+
+- decorators
+- [Decorators object](./decorators.md)
+- Additional decorator configuration for this API.
+
+---
+
+- preprocessors
+- [Decorators object](./decorators.md)
+- Preprocessors run before linting, and follow the same structure as decorators. We recommend the use of decorators over preprocessors in most cases.
+
+{% /table %}
+
+## Examples
+
+The following example shows a simple `redocly.yaml` configuration file with settings for multiple APIs.
+
+```yaml
+apis:
+  orders@v3:
+    root: orders/openapi.yaml
+    rules:
+      tags-alphabetical: error
+      operation-operationId-unique: error
+      spec-strict-refs: error
+  newsletter:
+    root: newsletter/openapi.yaml
+    rules:
+      info-contact: off
+      operation-summary: off
+```
+
+## Related options
+
+- [extends](./extends.md) sets the base ruleset to use.
+- [rules](./rules.md) settings define the linting rules that are used.
+- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
+
+## Resources
+
+- More information and examples of [per-API configuration](../apis.md).
+- List of [built-in rules](../../rules/built-in-rules.md).

docs/configuration/reference/decorators.md

@@ -0,0 +1,91 @@
+# `decorators`
+
+## Introduction
+
+The `decorators` configuration section defines the transformation steps that are applied to your API description when it is bundled.
+Both the [built-in decorators](../../decorators.md) and [decorators from custom plugins](../../custom-plugins/custom-decorators.md) are configured in this section.
+The `decorators` block can be used at the root of a configuration file, or inside an [API-specific section](./apis.md).
+
+## Options
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- {decorator name}
+- string _or_ [Decorator object](#decorator-object)
+- **REQUIRED**. You can add as many decorators as you wish. The keys must be either built-in decorators (for example `info-description-override`), or a decorator from a plugin (for example `tags-plugin/no-unused-tags`). Set the value to `on` or `off` to enable or disable a decorator, or use a [Decorator object](#decorator-object) to configure additional options for a specific decorator.
+
+{% /table %}
+
+### Decorator object
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- {additional properties}
+- any
+- Some decorators support additional configuration, check the documentation for each specific decorator to discover the values that can be used. For example the [`filter-out` decorator](../../decorators/filter-out.md) supports `property` and `value` settings for what to filter.
+
+---
+
+- severity
+- string
+- Severity level of any problems reported with this decorator. Setting this option is usually only useful for troubleshooting purposes. The value must be one of `error`, `warn`, or `off`, where `off` disables the decorator.
+
+{% /table %}
+
+## Examples
+
+This section covers some examples and common use cases.
+
+### Configure built-in decorators
+
+Pick and mix the built-in decorators in your `redocly.yaml` file as you need to.
+The following example enables the `remove-unused-components` decorator, and uses `info-override` to update the title:
+
+```yaml
+decorators:
+  remove-unused-components: on
+  info-override:
+    title: Better title than before
+```
+
+The `info-override` decorator accepts some additional configuration.
+
+### Configure decorators from custom plugins
+
+Redocly also supports [custom plugins](../../custom-plugins/custom-rules.md) for advanced users.
+Decorators in custom plugins are also configured in the `decorators` section of the configuration file, using the plugin's module name as a prefix.
+
+The following example shows enabling a decorator called `alphabetical` from a plugin named `tag-sorting`:
+
+```yaml
+plugins:
+  - './tag-sorting.js'
+
+decorators:
+  tag-sorting/alphabetical: on
+```
+
+The example includes adding the plugin, partly to remind you that this is also needed.
+
+## Related options
+
+- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
+- [rules](./rules.md) settings define the linting rules that are used.
+
+## Resources
+
+- Learn more about [decorators](../../decorators.md).
+- To build your own decorators, you can use [custom plugins](../../custom-plugins/index.md).
+- The [Redocly CLI cookbook](https://github.com/Redocly/redocly-cli-cookbook) is a great resource for learning and sharing decorators and custom plugins.

docs/configuration/reference/extends.md

@@ -0,0 +1,41 @@
+# `extends`
+
+## Introduction
+
+The `extends` configuration entry allows your project configuration to extend an existing configuration set.
+Multiple values are supported, and can include:
+
+- the name of a [built-in ruleset](../../rules.md#rulesets)
+- configuration defined in a [custom plugin](../../custom-plugins/index.md)
+- a path or URL to another `redocly.yaml` file
+
+Extends is useful if you use a common ruleset across multiple projects.
+Define a ruleset in one location, and each project can `extend` it, with or without modification.
+
+{% admonition type="info" name="Default ruleset: recommended" %}
+If there is no `redocly.yaml` configuration file, the [recommended ruleset](../../rules/recommended.md) is used by default.
+{% /admonition %}
+
+## Options
+
+The `extends` configuration is an array of strings.
+
+The array is parsed in the order it is defined, so the later entries in the array overwrite the earlier ones.
+
+## Examples
+
+To get started, try the following example to configure your project to be based on the [minimal ruleset](../../rules/minimal.md):
+
+```yaml
+extends:
+ - minimal
+```
+
+## Related options
+
+- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
+- [rules](./rules.md) settings define the linting rules that are used.
+
+## Resources
+
+- Detailed documentation and examples on [extending configuration](../extends.md).

docs/configuration/reference/plugins.md

@@ -0,0 +1,34 @@
+# `plugins`
+
+## Introduction
+
+Redocly supports [custom plugins](../../custom-plugins/index.md) for extending lint and decorator behavior.
+Use plugins when you need to add rules beyond the [built-in](../../rules/built-in-rules.md) and [configurable](../../rules/configurable-rules.md), or decorators beyond the [built-in decorators](../../decorators.md).
+
+## Options
+
+The `plugins` configuration is an array of paths to plugin files, relative to the config file.
+You can include as many plugins as you need.
+
+## Examples
+
+A basic example of including two plugins from a directory named `plugins/` is shown in the example below:
+
+```yaml
+plugins:
+  - plugins/my-best-plugin.js
+  - plugins/another-plugin.js
+```
+
+Remember that you need to include plugins in the `plugins` section before you can use the content of the plugin elsewhere in the configuration file.
+
+## Related options
+
+- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
+- [rules](./rules.md) settings define the linting rules that are used.
+- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
+
+## Resources
+
+- The [Redocly CLI cookbook](https://redocly.com/blog/redocly-cli-cookbook/) has many examples of plugins.
+- Read more [configuration examples](../index.md).

docs/configuration/reference/preprocessors.md

@@ -0,0 +1,16 @@
+# `preprocessors`
+
+## Introduction
+
+Preprocessors are similar to decorators, but they run before linting rather than after.
+
+Refer to the [`decorator` configuration options](./decorators.md) documentation for details; the options available are the same in both the `decorators` and `preprocessor` sections of the configuration file.
+
+## Related options
+
+- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
+- [plugins](./plugins.md) allow code extensions to extend the existing functionality.
+
+## Resources
+
+- [Custom plugins](../../custom-plugins/index.md) offer a way to extend the functionality of Redocly.

docs/configuration/reference/resolve.md

@@ -0,0 +1,90 @@
+# `resolve`
+
+## Introduction
+
+The `resolve` configuration provides options for how URLs in API descriptions are handled.
+If a URL is not publicly accessible, use these configuration settings to add the needed details to gain access.
+
+{% admonition type="info" %}
+One HTTP header is supported for each URL resolved.
+{% /admonition %}
+
+## Options
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- doNotResolveExamples
+- boolean
+- When running `lint`, set this option to `true` to avoid resolving `$ref` fields in examples. Resolving `$ref`s in other parts of the API is unaffected.
+
+---
+
+- http
+- [HTTP object](#http-object)
+- Describe URL patterns and the corresponding headers to use when resolving references that point to them.
+
+{% /table %}
+
+### HTTP object
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- matches
+- string
+- **REQUIRED**. The URL pattern to match, for example `https://api.example.com/v2/**` or `https://example.com/*/test.yaml`.
+
+---
+
+- name
+- string
+- **REQUIRED**. The header name, for example `Authorization`.
+
+---
+
+- value
+- string
+- The value to send for the header. Only one of `value` or `envVariable` can be used; `envVariable` is recommended for any secrets.
+
+---
+
+- envVariable
+- string
+- The name of the environment variable that contains the value to send for the header. Only one of `value` or `envVariable` can be used; `envVariable` is recommended for any secrets.
+
+{% /table %}
+
+## Examples
+
+If you have multiple examples to resolve, you can describe multiple entries with patterns to match and headers to include.
+The following example shows two patterns, with the names of environment variables that contain the values to use.
+
+```text
+resolve:
+  http:
+    headers:
+      - matches: https://api.example.com/v2/**
+        name: X-API-KEY
+        envVariable: SECRET_KEY
+      - matches: https://example.com/*/test.yaml
+        name: Authorization
+        envVariable: SECRET_AUTH
+```
+
+When the OpenAPI description references a URL that matches these patterns, it is resolved using the additional header specified.
+
+## Resources
+
+- [Configuration for Redocly CLI](../index.md).
+- [How to use `$ref` in OpenAPI](https://redocly.com/docs/resources/ref-guide/).