docs: Update from review feedback

Redocly · Mar 25, 2024 · 214667c · 214667c
1 parent fa3a94d
commit 214667c
Show file tree

Hide file tree

Showing 3 changed files with 10 additions and 3 deletions.
diff --git a/docs/configuration/reference/apis.md b/docs/configuration/reference/apis.md
@@ -16,7 +16,7 @@ If your project contains multiple APIs, the `apis` configuration section allows
 
 - `{name}@{version}`
 - [API object](#api-object)
-- Required. Each API needs a name and optionally a version.
+- Required. Each API needs a name and optionally a version. Supports alphanumeric characters and underscores.
 
 {% /table %}
 
@@ -46,6 +46,12 @@ If your project contains multiple APIs, the `apis` configuration section allows
 - [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 use of decorators in most cases.
+
 {% /table %}
 
 ## Examples
@@ -54,7 +60,7 @@ The following example shows a simple `redocly.yaml` configuration file with sett
 
 ```yaml
 apis:
-  orders:
+  orders@v3:
     root: orders/openapi.yaml
     rules:
       tags-alphabetical: error

diff --git a/docs/configuration/reference/decorators.md b/docs/configuration/reference/decorators.md
@@ -87,4 +87,5 @@ The example includes adding the plugin, partly to remind you that this is also n
 ## 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.
diff --git a/docs/configuration/reference/extends.md b/docs/configuration/reference/extends.md
@@ -13,7 +13,7 @@ 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 `extends` isn't set, the [recommended ruleset](../../rules/recommended.md) is used by default.
+If there is no `redocly.yaml` configuration file, the [recommended ruleset](../../rules/recommended.md) is used by default.
 {% /admonition %}
 
 ## Options