diff --git a/docs/changelog.md b/docs/changelog.md
index 82c00ab067..582d52e460 100644
--- a/docs/changelog.md
+++ b/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
 
diff --git a/docs/commands/completion.md b/docs/commands/completion.md
index d4a923f37e..000d428315 100644
--- a/docs/commands/completion.md
+++ b/docs/commands/completion.md
@@ -22,7 +22,7 @@ redocly completion
 
 Outputs something like this:
 
-```
+```sh
 ###-begin-redocly-completions-###
 #
 # yargs command completion script
diff --git a/docs/custom-plugins/extended-types.md b/docs/custom-plugins/extended-types.md
index e98d6c28ec..575ebffe11 100644
--- a/docs/custom-plugins/extended-types.md
+++ b/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.
-
diff --git a/docs/custom-plugins/visitor.md b/docs/custom-plugins/visitor.md
index a1a1932f18..acdef366fb 100644
--- a/docs/custom-plugins/visitor.md
+++ b/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
diff --git a/docs/decorators/media-type-examples-override.md b/docs/decorators/media-type-examples-override.md
index 9e333d0c13..79fe5149fe 100644
--- a/docs/decorators/media-type-examples-override.md
+++ b/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:
 
diff --git a/docs/decorators/tag-description-override.md b/docs/decorators/tag-description-override.md
index d4e5c75299..9f2db86e74 100644
--- a/docs/decorators/tag-description-override.md
+++ b/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
diff --git a/docs/file-management.md b/docs/file-management.md
index 84ee092bad..0e4d324d79 100644
--- a/docs/file-management.md
+++ b/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
 ```
 
diff --git a/docs/guides/lint-asyncapi.md b/docs/guides/lint-asyncapi.md
index e276f81542..b1ddcfc79e 100644
--- a/docs/guides/lint-asyncapi.md
+++ b/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
 ```
 
diff --git a/docs/guides/migrate-from-redoc-cli.md b/docs/guides/migrate-from-redoc-cli.md
index e59ba15c0e..83520d718a 100644
--- a/docs/guides/migrate-from-redoc-cli.md
+++ b/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
 ```
 
diff --git a/docs/guides/migrate-from-spectral.md b/docs/guides/migrate-from-spectral.md
index 1a082df37b..0bbee13402 100644
--- a/docs/guides/migrate-from-spectral.md
+++ b/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.
 
diff --git a/docs/guides/migrate-from-swagger-cli.md b/docs/guides/migrate-from-swagger-cli.md
index decd9069c9..51cf13ed7a 100644
--- a/docs/guides/migrate-from-swagger-cli.md
+++ b/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
 ```
 
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 677d5fcbcc..3e79325b9f 100644
--- a/docs/quickstart.md
+++ b/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:
 
diff --git a/docs/rules/required-string-property-missing-min-length.md b/docs/rules/required-string-property-missing-min-length.md
index 45ebc9694a..4860647fe3 100644
--- a/docs/rules/required-string-property-missing-min-length.md
+++ b/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). |
diff --git a/docs/rules/scalar-property-missing-example.md b/docs/rules/scalar-property-missing-example.md
index b3c244b94b..94d0535730 100644
--- a/docs/rules/scalar-property-missing-example.md
+++ b/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). |
diff --git a/docs/rules/tag-description.md b/docs/rules/tag-description.md
index c9d6c50752..c92e8557fb 100644
--- a/docs/rules/tag-description.md
+++ b/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:
diff --git a/docs/usage-data.md b/docs/usage-data.md
index 153bf543e1..f983e9e749 100644
--- a/docs/usage-data.md
+++ b/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.