diff --git a/.changeset/bright-steaks-walk.md b/.changeset/bright-steaks-walk.md new file mode 100644 index 00000000..8165a1e2 --- /dev/null +++ b/.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. diff --git a/.github/sync.yml b/.github/sync.yml deleted file mode 100644 index 20b15e35..00000000 --- a/.github/sync.yml +++ /dev/null @@ -1,3 +0,0 @@ -Redocly/docs: - - source: docs/ - dest: docs/cli/ \ No newline at end of file diff --git a/.github/workflows/docs-tests.yaml b/.github/workflows/docs-tests.yaml new file mode 100644 index 00000000..a1019a06 --- /dev/null +++ b/.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 diff --git a/.github/workflows/mlc-link-check.yaml b/.github/workflows/mlc-link-check.yaml deleted file mode 100644 index 08ded39b..00000000 --- a/.github/workflows/mlc-link-check.yaml +++ /dev/null @@ -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 diff --git a/.github/workflows/sync.yml b/.github/workflows/sync.yml deleted file mode 100644 index b41aa879..00000000 --- a/.github/workflows/sync.yml +++ /dev/null @@ -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 diff --git a/.github/workflows/vale.yaml b/.github/workflows/vale.yaml deleted file mode 100644 index c5220c41..00000000 --- a/.github/workflows/vale.yaml +++ /dev/null @@ -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}} diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..ab1a86e5 --- /dev/null +++ b/.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 diff --git a/.prettierignore b/.prettierignore index fbe3d0f6..2ec79b78 100644 --- a/.prettierignore +++ b/.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 diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 88% rename from .github/CONTRIBUTING.md rename to CONTRIBUTING.md index 7c82126a..19daf744 100644 --- a/.github/CONTRIBUTING.md +++ b/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/ ``` diff --git a/README.md b/README.md index fa468c7b..3895de01 100644 --- a/README.md +++ b/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 ``` diff --git a/docs/changelog.md b/docs/changelog.md index b8742b64..a86c97fe 100644 --- a/docs/changelog.md +++ b/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 diff --git a/docs/configuration/index.md b/docs/configuration/index.md index fd70a4a3..fcb60fac 100644 --- a/docs/configuration/index.md +++ b/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. diff --git a/docs/configuration/rules.md b/docs/configuration/rules.md index 0b580b04..8b0f9c04 100644 --- a/docs/configuration/rules.md +++ b/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. diff --git a/docs/guides/migrate-from-redoc-cli.md b/docs/guides/migrate-from-redoc-cli.md index 83520d71..28a77d47 100644 --- a/docs/guides/migrate-from-redoc-cli.md +++ b/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. -By default the documentation is available on `http://127.0.0.1:8080` but this is configurable. +The documentation output updates when the API description changes. +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 %} diff --git a/docs/guides/migrate-from-swagger-cli.md b/docs/guides/migrate-from-swagger-cli.md index 8094eda3..eb6e96d9 100644 --- a/docs/guides/migrate-from-swagger-cli.md +++ b/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 diff --git a/docs/rules/built-in-rules.md b/docs/rules/built-in-rules.md index d54f0833..93576ce6 100644 --- a/docs/rules/built-in-rules.md +++ b/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 diff --git a/package.json b/package.json index dbf072ef..9027482f 100644 --- a/package.json +++ b/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:check": "npx prettier --check \"**/*.{ts,js,yaml,json}\"", + "prettier": "npx prettier --write \"**/*.{ts,js,yaml,json,md}\"", + "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 ", diff --git a/packages/core/README.md b/packages/core/README.md index 9160552c..b66f3306 100644 --- a/packages/core/README.md +++ b/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. -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. -If your use case is not documented below, please open an issue. +> 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. +> Avoid using any functions or features that are not documented below. +> 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; -``` \ No newline at end of file +```