docs: Update docs tooling and checks (#1330)

* fix: Remove github token with incorrect access

* docs: Improve uninstall CTA in migration guide

* fix: Update checkout action version for vale

* docs: Vale reports errors in any edited file

* docs: Update to make Vale happy

* docs: Markdownlint fixes

* fix: Remove sync actions as this integration is no longer used

* core: Add markdownlint config and github action

Uses rules from https://github.com/Redocly/marketing-site-portal/pull/1142

* chore: Move contributing file to top level

* chore: Add markdown to the file types that we want prettier to operate on

* fix: Make files fit prettier rules, ignore LICENSE since we can't change that

* chore: Combine docs-related workflows into one for simplicity

* docs: Add instructions for running the CLI docs standalone from this repo

* chore: Add changeset, this docs change is quite large

* Update .changeset/bright-steaks-walk.md

Co-authored-by: Ihor Karpiuk <106662428+IgorKarpiuk@users.noreply.github.com>

---------

Co-authored-by: Ihor Karpiuk <106662428+IgorKarpiuk@users.noreply.github.com>

.changeset/bright-steaks-walk.md

@@ -0,0 +1,5 @@
+---
+"@redocly/cli": patch
+---
+
+Support standalone docs development to facilitate more contributors, add docs quality checks to CI.

.github/sync.yml

@@ -1,3 +0,0 @@
-Redocly/docs:
-  - source: docs/
-    dest: docs/cli/

.github/workflows/docs-tests.yaml

@@ -0,0 +1,35 @@
+name: Documentation tests
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  markdownlint:
+    name: markdownlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: articulate/actions-markdownlint@v1
+        with:
+          config: .markdownlint.yaml
+          files: 'docs/**/*.md'
+
+  vale:
+    name: vale action
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: '["README.md", "docs"]'
+          filter_mode: file
+
+  linkcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Markup Link Checker (mlc)
+        uses: becheran/mlc@v0.16.1
+        with:
+          args: ./docs

.github/workflows/mlc-link-check.yaml

@@ -1,17 +0,0 @@
-name: Check links
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-  push:
-    branches:
-      - main
-jobs:
-  linkcheck:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v2
-      - name: Markup Link Checker (mlc)
-        uses: becheran/mlc@v0.16.1
-        with:
-          args: ./docs

.github/workflows/sync.yml

@@ -1,18 +0,0 @@
-name: Sync Files
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v2
-      - name: Run GitHub File Sync
-        uses: Redocly/repo-file-sync-action@main
-        with:
-          GH_PAT: ${{ secrets.GH_PAT }}
-          COMMIT_PREFIX: "sync:"
-          SKIP_PR: true

.github/workflows/vale.yaml

@@ -1,16 +0,0 @@
-name: Docs lint
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-jobs:
-  vale:
-    name: vale action
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: errata-ai/vale-action@reviewdog
-        with:
-          files: '["README.md", "docs"]'
-        env:
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.markdownlint.yaml

@@ -0,0 +1,54 @@
+---
+# Default rules: https://github.com/github/super-linter/blob/master/TEMPLATES/.markdown-lint.yml
+
+# Rules by id
+
+# Unordered list style
+MD004: false
+
+# Unordered list indentation
+MD007:
+  indent: 2
+
+MD013:
+  # TODO: Consider to decrease allowed line length
+  line_length: 800
+  tables: false
+
+## Allow same headers in siblings
+MD024:
+  siblings_only: true
+
+# Multiple top level headings in the same document
+MD025:
+  front_matter_title: ''
+
+# Trailing punctuation in heading
+MD026:
+  punctuation: '.,;:。，；:'
+
+# Ordered list item prefix
+MD029: false
+
+# Unordered lists inside of ordered lists
+MD030: false
+
+# Inline HTML
+MD033: false
+
+# No bare urls
+MD034: false
+
+# Emphasis used instead of a heading
+MD036: false
+
+# Disable "First line in file should be a top level heading"
+# We use uncommon format to add metadata.
+# TODO: Consider to use "YAML front matter".
+MD041: false
+
+# Rules by tags
+blank_lines: false
+
+MD046: false
+# code-block-style

.prettierignore

@@ -5,3 +5,4 @@ output/
 *snapshot.js
 packages/core/src/rules/__tests__/fixtures/invalid-yaml.yaml
 __tests__/webpack-bundle/bundle-workflows/metafile.json
+LICENSE.md

CONTRIBUTING.md

@@ -35,7 +35,7 @@ Before submitting a pull request, please make sure the following is done:
 After forking the repo, run:
 
 ```bash
-$ npm install # or npm i
+npm install # or npm i
 ```
 
 ### Commonly used NPM scripts
@@ -93,21 +93,37 @@ Don't forget to revert the changes to **package.json** files later.
 
 ## Contribute documentation
 
+Additions and updates to our documentation are very welcome. You can find the documentation in the `docs/` folder, and this is published to https://redocly.com/docs/cli/ as part of our main website.
+
+To preview your changes locally, run this command from the `docs/` folder:
+
+```bash
+https://redocly.com/docs/cli/
+```
+
+> Please note that currently the custom markdoc tags used in the main website are not available in the local preview version, and links that point to the wider website do show as errors when using a local platform. The pull request workflows generate a full preview, so rest assured that you are able to check everything is in good shape before we review and merge your changes.
+
 ### Prose linting
 
 We are proud of our docs. When you open a pull request, we lint the prose using [Vale](https://vale.sh/). You can also install this tool locally and run it from the root of the project with:
 
-```
+```bash
 vale docs/
 ```
 
 The configuration is in `.vale.ini` in the root of the project.
 
+### Markdown linting
+
+We use [Markdownlint](https://github.com/DavidAnson/markdownlint) to check that the Markdown in our docs is well formatted. The checks run as part of the pull request, and you can also run this tool locally. Follow the instructions from the markdownlint project page, and then run `markdownlint docs/` in the top-level folder of this repository.
+
+> Note that prettier also runs and reformats Markdown files. Use `npm run prettier` from the root of the project.
+
 ### Markdown link checking
 
 We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder. This tool runs automatically on every pull request, but you can also run it locally if you want to. Visit the project homepage to find the installation instructions for your platform, and then run the command like this:
 
-```
+```bash
 mlc docs/
 ```
 

README.md

@@ -12,19 +12,19 @@
 
 ### Node
 
-```
+```sh
 npx @redocly/cli lint path-to-root-file.yaml
 ```
 
 Alternatively, install it globally with `npm`:
 
-```
+```sh
 npm install @redocly/cli -g
 ```
 
 Then you can use it as `redocly [command] [options]`, for example:
 
-```
+```sh
 redocly lint path-to-root-file.yaml
 ```
 
@@ -36,13 +36,13 @@ To give the Docker container access to the OpenAPI description files, you need t
 mount the containing directory as a volume. Assuming the API description is rooted
 in the current working directory, you need the following command:
 
-```
+```sh
 docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
 ```
 
 To build and run with a local image, run the following from the project root:
 
-```
+```sh
 docker build -t redocly/cli .
 docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
 ```
@@ -53,7 +53,7 @@ docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
 
 Redocly CLI is a great way to render API reference documentation. It uses open source [Redoc](https://github.com/redocly/redoc) to build your documentation. Use a command like this:
 
-```
+```sh
 redocly build-docs openapi.yaml
 ```
 
@@ -73,7 +73,7 @@ Our API linter is designed for speed on even large documents, and it's easy to r
 
 Try it like this:
 
-```
+```sh
 redocly lint openapi.yaml
 ```
 

docs/changelog.md

@@ -31,7 +31,7 @@ toc:
 ### Minor Changes
 
 - Added the possibility to configure the linting severity level of the configuration file for all CLI commands.
-  Redocly CLI will exit with an error if there are any issues with the configuration file, and the severity is set to `error`.
+  Redocly CLI exits with an error if there are any issues with the configuration file, and the severity is set to `error`.
 
 ### Patch Changes
 

docs/configuration/index.md

@@ -78,7 +78,7 @@ Learn about the various sections of the config file, and follow the links for de
 Use `extends` to adopt an existing [ruleset](../rules.md#rulesets) such as the `recommended` or `minimal` standards.
 You can also define your own rulesets and refer to them here by file path or URL.
 
-While the order of the sections in the configuration file doesn't matter, usually `extends` is first, and any later rules, preprocessors or decorators defined in this file will override the base settings.
+While the order of the sections in the configuration file doesn't matter, usually `extends` is first, and any later rules, preprocessors or decorators defined in this file then override the base settings.
 
 Read the [detailed `extends` documentation](./extends.md) to see more information and examples.
 

docs/configuration/rules.md

@@ -1,4 +1,4 @@
-# Configuring rules
+# Configure your linting rules
 
 Use individual rules to make the API linting fit your API needs. Start with the [recommended](../rules/recommended.md) or [minimal](../rules/minimal.md) ruleset, then adjust as needed.
 

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

@@ -14,7 +14,7 @@ Visit the [installation page](../installation.md) to find and use an installatio
 
 All Redocly CLI commands use a common configuration file. For theme options, linting rules, and other configuration, check out the [configuration documentation](../configuration/index.md) for all the details.
 
-### Developing documentation
+### Preview documentation locally
 
 Replace the old `redoc-cli serve` with:
 
@@ -22,8 +22,8 @@ Replace the old `redoc-cli serve` with:
 redocly preview-docs --use-community-edition openapi.yaml
 ```
 
-The documentation will update when the spec file changes.
+The documentation output updates when the API description changes.
-By default the documentation is available on `http://127.0.0.1:8080` but this is configurable.
+By default the documentation is available on `http://127.0.0.1:8080` but you can configure the host and port.
 
 The `--use-community-edition` parameter is needed for the tool to use Redoc to generate the docs; otherwise it generates the preview for our hosted [API reference docs](https://redocly.com/reference/)
 
@@ -31,7 +31,7 @@ The `--use-community-edition` parameter is needed for the tool to use Redoc to g
 Visit the [`preview-docs` documentation](../commands/preview-docs.md) for more information and examples
 {% /admonition %}
 
-### Publishing documentation
+### Publish documentation
 
 Replace existing `redoc-cli build` commands with:
 
@@ -107,5 +107,5 @@ The newer tool has a lot more functionality than `redoc-cli` had, so explore the
 - Enhancing an OpenAPI description with decorators
 
 {% admonition type="warning" name="Uninstall" %}
-It's recommended to uninstall `redoc-cli` now that it is no longer needed
+We recommend you uninstall `redoc-cli` now that it is no longer needed.
 {% /admonition %}

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

@@ -27,7 +27,7 @@ You can run these commands locally, as part of your CI (continuous integration)
 
 ### Structure validation only
 
-In some cases, the additional rules from linting won't be useful. For instance, in the case of legacy APIs that won't be updated to meet more modern API expectations. To restrict Redocly to only checking that the API description meets the expected structure for OpenAPI, use a `redocly.yaml` file to configure a ruleset that contains only the `spec` rule.
+In some cases, checking additional rules during lint is less useful. For instance, in the case of legacy APIs that are no longer updated to meet more modern API expectations. To restrict Redocly to only checking that the API description meets the expected structure for OpenAPI, use a `redocly.yaml` file to configure a ruleset that contains only the `spec` rule.
 
 The configuration in the `redocly.yaml` file should look like this:
 
@@ -38,7 +38,7 @@ rule:
   spec: error
 ```
 
-Redocly CLI will automatically detect the configuration file, so your command should be:
+Redocly CLI automatically detects the `redocly.yaml` configuration file, so your command should be:
 
 ```sh
 redocly lint openapi.yml

docs/rules/built-in-rules.md

@@ -13,6 +13,10 @@ The _Special rules_ group contains rules that may apply to multiple objects or t
 Build [configurable rules](./configurable-rules.md) if the rule you need isn't listed.
 {% /admonition %}
 
+## List of available rules
+
+Details of all the rules available "out of the box" with Redocly CLI are listed below. Visit each individual page for details of what the rule does, additional configuration options, and examples of it in use.
+
 ### Special rules
 
 - [no-unresolved-refs](./no-unresolved-refs.md): Every `$ref` must exist

package.json

@@ -16,8 +16,8 @@
     "coverage:core": "npm run jest -- --roots packages/core/src --coverage",
     "typecheck": "tsc --noEmit --skipLibCheck",
     "e2e": "npm run webpack-bundle -- --mode=none && REDOCLY_TELEMETRY=off jest --roots=./__tests__/",
-    "prettier": "npx prettier --write \"**/*.{ts,js,yaml,json}\"",
+    "prettier": "npx prettier --write \"**/*.{ts,js,yaml,json,md}\"",
-    "prettier:check": "npx prettier --check \"**/*.{ts,js,yaml,json}\"",
+    "prettier:check": "npx prettier --check \"**/*.{ts,js,yaml,json,md}\"",
     "eslint": "eslint packages/**",
     "clean": "rm -rf packages/**/lib packages/**/node_modules packages/**/*.tsbuildinfo package-lock.json node_modules",
     "watch": "tsc -b tsconfig.build.json --watch ",

packages/core/README.md

@@ -3,10 +3,10 @@
 See https://github.com/Redocly/redocly-cli
 
 > [!IMPORTANT]
-The `openapi-core package` is designed for our internal use; the interfaces that are considered safe to use are documented below.
+> The `openapi-core package` is designed for our internal use; the interfaces that are considered safe to use are documented below.
-Some of the function arguments are not documented below because they are not intended for public use.
+> Some of the function arguments are not documented below because they are not intended for public use.
-Avoid using any functions or features that are not documented below.
+> Avoid using any functions or features that are not documented below.
-If your use case is not documented below, please open an issue.
+> If your use case is not documented below, please open an issue.
 
 ## Basic usage
 
@@ -265,4 +265,4 @@ Helper function to stringify a javascript object to YAML.
 
 ```ts
 function stringifyYaml(obj: object): string;
-```
+```