sync: Synced local 'docs/' with remote 'docs/cli/'

docs/changelog.md

@@ -345,10 +345,10 @@ theme:
 ### Changes
 
 - Renamed four type names for alignment with the OpenAPI specification.
-    - `PathsMap` to `Paths`
-    - `ResponsesMap` to `Responses`
-    - `EncodingsMap` to `EncodingMap`
-    - `SecuritySchemeFlows` to `OAuth2Flows`
+  - `PathsMap` to `Paths`
+  - `ResponsesMap` to `Responses`
+  - `EncodingsMap` to `EncodingMap`
+  - `SecuritySchemeFlows` to `OAuth2Flows`
 
 ### Features
 
@@ -602,7 +602,7 @@ rules:
 
 ### Features
 
-- Added the `--separator` option to the `split` command. Use it to change the separator character that's used instead of whitespace in file names. The default is `_ `, which means that after splitting, path file names look like this: "user_login.yaml", "user_logout", etc.
+- Added the `--separator` option to the `split` command. Use it to change the separator character that's used instead of whitespace in file names. The default is `_`, which means that after splitting, path file names look like this: "user_login.yaml", "user_logout", etc.
 
 ### Fixes
 

docs/commands/completion.md

@@ -22,7 +22,7 @@ redocly completion
 
 Outputs something like this:
 
-```
+```sh
 ###-begin-redocly-completions-###
 #
 # yargs command completion script

docs/custom-plugins/extended-types.md

@@ -7,7 +7,7 @@ The type tree is built from top level `Types` which can link to child types. For
 
 The type tree can be extended by exporting the `typeExtension` function from a custom plugin.
 
-# Type extension example
+## Type extension example
 
 Consider an OpenAPI that uses an (imaginary) specification extension `x-metadata` which must contain information about the lifecycle state of the API, and which team owns the API. A snippet of the OpenAPI to show the example clearly:
 
@@ -71,4 +71,3 @@ rules:
 ```
 
 Now lint your API description with `redocly lint openapi.yaml` and try removing the `lifecycle` field from within the `x-metadata` section. It's a required field, so you see an error if it's missing.
-

docs/custom-plugins/visitor.md

@@ -103,7 +103,7 @@ put:
 
 The visitor above logs the following:
 
-```
+```sh
 type string from getOp
 type object from getOp
 type number from putOp

docs/decorators/media-type-examples-override.md

@@ -30,7 +30,7 @@ decorators:
             application/json: ./pet-errors-examples.yaml
 ```
 
-## Examples 
+## Examples
 
 Given this API description with example:
 

docs/decorators/tag-description-override.md

@@ -6,7 +6,7 @@ Replaces the tag description with the designated Markdown in the corresponding f
 
 Sometimes developers generate OpenAPI and the descriptions need to be improved after the fact.
 This generally happens when you have no permission to edit the source.
-This decorator provides a way to "overlay" a new description over the source so that as the source changes, the modifications can be reapplied. 
+This decorator provides a way to "overlay" a new description over the source so that as the source changes, the modifications can be reapplied.
 
 
 ## Configuration

docs/file-management.md

@@ -13,7 +13,7 @@ OpenAPI is designed with support for `$ref` syntax, allowing parts of an API des
 
 If you have one large single file, split it up like this:
 
-```
+```sh
 redocly split openapi.yaml --outDir myApi
 ```
 
@@ -32,7 +32,7 @@ Some tools require one file, so it's likely that you may need this step at some
 
 Use the bundle command like this:
 
-```
+```sh
 redocly bundle openapi.yaml -o bundled.yaml
 ```
 
@@ -52,7 +52,7 @@ When you have multiple APIs but want to publish a single API description file, t
 
 Use the command to combine files like this:
 
-```
+```sh
 redocly join api1.yaml api2.yaml -o apis-combined.yaml
 ```
 
@@ -62,7 +62,7 @@ Supply as many API descriptions as you need to; the first one is used for the `i
 
 It's sometimes nice to get an overall view of complex API descriptions. Redocly CLI has a [`stats`](./commands/stats.md) command that gives a simple overview of what's in a file.
 
-```
+```sh
 redocly stats openapi.yaml
 ```
 

docs/guides/lint-asyncapi.md

@@ -38,7 +38,7 @@ specification.
 
 With this configuration file, and your AsyncAPI description file (or use one of the [existing examples](https://github.com/asyncapi/spec/tree/master/examples)), run the linting command:
 
-```
+```sh
 redocly lint asyncapi.yaml
 ```
 

docs/guides/migrate-from-redoc-cli.md

@@ -18,7 +18,7 @@ All Redocly CLI commands use a common configuration file. For theme options, lin
 
 Replace the old `redoc-cli serve` with:
 
-```
+```sh
 redocly preview-docs --use-community-edition openapi.yaml
 ```
 
@@ -35,7 +35,7 @@ Visit the [`preview-docs` documentation](../commands/preview-docs.md) for more i
 
 Replace existing `redoc-cli build` commands with:
 
-```
+```sh
 redocly build-docs openapi.yaml
 ```
 
@@ -45,7 +45,7 @@ This generates a zero-dependency HTML file with your docs in, named `redoc-stati
 
 If you have your OpenAPI description split between multiple files, replace `redoc-cli bundle` with `redocly bundle`:
 
-```
+```sh
 redocly bundle openapi.yaml -o all-in-one.yaml
 ```
 
@@ -72,7 +72,7 @@ Replace your existing `--options.theme.*` settings with a new prefix: `--theme.o
 
 For example if you used `redoc-cli build --options.theme.sidebar.width='300px' openapi.yaml` then the new command would be:
 
-```
+```sh
 redocly build-docs --theme.openapi.theme.sidebar.width='300px' openapi.yaml
 ```
 

docs/guides/migrate-from-spectral.md

@@ -131,11 +131,11 @@ Included here is an attempt to map the simliar-but-not-identical naming of rules
 If the built-in rules don't meet your requirements, don't worry! Redocly allows you to build any rule to meet your needs, using [configurable rules](../rules/configurable-rules.md). Declare which elements of the OpenAPI description should comply with the rule, and then define the criteria that it should be checked against.
 
 Build up the rulesets that work for your organization's API standards. These can be:
- - using existing Redocly rulesets
- - defining your own rulesets from built-in, configurable and/or custom rules
- - combining rulesets from any source
- - adding per-API additions or exceptions as required
- - using an ignore file to overlook existing/historic incompatibilities while still enforcing rules for changed elements
+- using existing Redocly rulesets
+- defining your own rulesets from built-in, configurable and/or custom rules
+- combining rulesets from any source
+- adding per-API additions or exceptions as required
+- using an ignore file to overlook existing/historic incompatibilities while still enforcing rules for changed elements
 
 For some advanced use cases, the configurable rules can't cover all possibilities. If that happens, Redocly supports [adding rules in custom plugins](../custom-plugins/custom-rules.md) so that you can use JavaScript to express any specialist rules you need.
 

docs/guides/migrate-from-swagger-cli.md

@@ -13,13 +13,13 @@ While you have multiple options for [using Redocly CLI for better API standards]
 
 If the old command was:
 
-```
+```sh
 swagger-cli validate openapi.yml
 ```
 
 Then the new command is:
 
-```
+```sh
 redocly lint --extends=minimal openapi.yml
 ```
 
@@ -40,7 +40,7 @@ rule:
 
 Redocly CLI will automatically detect the configuration file, so your command should be:
 
-```
+```sh
 redocly lint openapi.yml
 ```
 
@@ -60,13 +60,13 @@ While the OpenAPI (and earlier Swagger) standards were designed to use `$ref` re
 
 With `swagger-cli` the command would be something like this:
 
-```
+```sh
 swagger-cli bundle openapi.yml
 ```
 
 With Redocly CLI the command to create a single file is:
 
-```
+```sh
 redocly bundle openapi.yml
 ```
 

docs/quickstart.md

@@ -10,7 +10,7 @@ Before you start:
 There's also an [openapi-starter](https://github.com/Redocly/openapi-starter) repository that you can clone and experiment with to get your bearings
 {% /admonition %}
 
-### Preview API documentation
+## Preview API documentation
 
 Redocly CLI has support for showing a preview of [Redoc](https://redocly.com/redoc/) rendering your API docs, which updates when the API description updates.
 Run the command:
@@ -25,7 +25,7 @@ Open that URL in your browser, and admire your lovely API documentation!
 
 ![Preview of API documentation](./images/preview-docs.png)
 
-### Lint an OpenAPI description
+## Lint an OpenAPI description
 
 The `lint` command is used to check that the OpenAPI description is compliant with a set of rules. You can define your own rules if you want to be specific, but to get started, try this:
 

docs/rules/required-string-property-missing-min-length.md

@@ -3,7 +3,7 @@ slug: /docs/cli/rules/required-string-property-missing-min-length
 ---
 # required-string-property-missing-min-length
 
-Requires that every required property in the API description with type `string` has a `minLength`. 
+Requires that every required property in the API description with type `string` has a `minLength`.
 
 |OAS|Compatibility|
 |---|---|
@@ -26,9 +26,6 @@ rules:
     severity: error
 ```
 
-## Configuration
-
-
 |Option|Type|Description|
 |---|---|---|
 |severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |

docs/rules/scalar-property-missing-example.md

@@ -29,9 +29,6 @@ rules:
     severity: error
 ```
 
-## Configuration
-
-
 |Option|Type|Description|
 |---|---|---|
 |severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |

docs/rules/tag-description.md

@@ -48,8 +48,6 @@ rules:
   info-contact: error
 ```
 
-## Configuration
-
 
 |Option|Type|Description|
 |---|---|---|
@@ -59,7 +57,7 @@ An example configuration:
 
 ```yaml
 rules:
-  : error
+  tag-description: error
 ```
 
 ## Examples
@@ -69,7 +67,7 @@ Given this configuration:
 
 ```yaml
 rules:
-  : error
+  tag-description: error
 ```
 
 Example of **incorrect** tags:

docs/usage-data.md

@@ -10,11 +10,11 @@ Redocly CLI sends a small set of anonymized data to help us understand how the t
 ## What data is collected
 
 When a command is run, the following data is collected:
- * the command being run
- * command exit code
- * values from `REDOCLY_ENVIRONMENT`
- * CLI version
- * Node.js and NPM versions
+* the command being run
+* command exit code
+* values from `REDOCLY_ENVIRONMENT`
+* CLI version
+* Node.js and NPM versions
 
 Values such as file names, organization IDs, and URLs are removed, replaced by just "URL" or "file", etc.