From 4fd22f6d74a7709c318d78005354e66b0afbc2b7 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 29 Jan 2024 16:39:44 +0000 Subject: [PATCH] docs: Add docs tooling to align with publishing to main site (#2484) * docs: add markdownlint and some link checks alongside vale * docs: add link checker config and fix/update some links reported broken * docs: update markdownlint action * docs: fix markdown table formatting * docs: Unpin Vale version and pick up the latest --- .github/workflows/docs-tests.yaml | 37 +++++++++++++++++++++ .github/workflows/vale.yaml | 16 --------- .markdownlint.yaml | 54 +++++++++++++++++++++++++++++++ .mlc.toml | 4 +++ README.md | 8 ++--- docs/config.md | 2 +- docs/deployment/cli.md | 4 +-- docs/deployment/intro.md | 4 +-- docs/redoc-vendor-extensions.md | 12 +++---- 9 files changed, 110 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/docs-tests.yaml delete mode 100644 .github/workflows/vale.yaml create mode 100644 .markdownlint.yaml create mode 100644 .mlc.toml diff --git a/.github/workflows/docs-tests.yaml b/.github/workflows/docs-tests.yaml new file mode 100644 index 00000000..66729455 --- /dev/null +++ b/.github/workflows/docs-tests.yaml @@ -0,0 +1,37 @@ +name: Documentation tests +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + markdownlint: + name: markdownlint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: DavidAnson/markdownlint-cli2-action@v15 + with: + config: .markdownlint.yaml + globs: | + docs/**/*.md + README.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/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/.mlc.toml b/.mlc.toml new file mode 100644 index 00000000..46b37072 --- /dev/null +++ b/.mlc.toml @@ -0,0 +1,4 @@ +# Ignore these links, we can't check them from this subproject +ignore-links=["../*", "/docs/*"] +# Path to the root folder used to resolve all relative paths +root-dir="./docs" diff --git a/README.md b/README.md index 8a06f76e..68e2b3e6 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@
Redoc logo - # Generate beautiful API documentation from OpenAPI +# Generate beautiful API documentation from OpenAPI [![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/main/LICENSE) - [![bundle size](http://img.badgesize.io/https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js?compression=gzip&max=300000)](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc) + [![bundle size](http://img.badgesize.io/https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js?compression=gzip&max=300000)](https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js) [![npm](https://img.shields.io/npm/dm/redoc.svg)](https://www.npmjs.com/package/redoc) [![jsDelivr status](https://data.jsdelivr.com/v1/package/npm/redoc/badge)](https://www.jsdelivr.com/package/npm/redoc)
@@ -38,7 +38,7 @@ enter the URL for your definition and select **TRY IT**. - High-level grouping in side menu with the [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension - [Simple integration with `create-react-app`](https://redocly.com/docs/redoc/quickstart/react/) - Code samples support (with vendor extension)
- ![](docs/images/code-samples-demo.gif) + ![code samples in action](docs/images/code-samples-demo.gif) ## Usage @@ -48,7 +48,7 @@ Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, If you have Node installed, quickly generate documentation using `npx`: -``` +```bash npx @redocly/cli build-docs openapi.yaml ``` diff --git a/docs/config.md b/docs/config.md index 9a668892..28e24f7e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -6,7 +6,7 @@ Each deployment type has documentation on how to configure options for that type **Versions: 2.x** -{% admonition type="success" name="Client-side configuration" %} +{% admonition type="success" name="Client-side configuration" %} Using Redoc as a standalone (HTML or React) tool, these options must be presented in [kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). For example, `scrollYOffset` becomes `scroll-y-offset`, and `expandResponses` becomes `expand-responses`. diff --git a/docs/deployment/cli.md b/docs/deployment/cli.md index 2a4c7198..8726248b 100644 --- a/docs/deployment/cli.md +++ b/docs/deployment/cli.md @@ -12,9 +12,9 @@ With Redocly CLI, you can bundle your OpenAPI definition and API documentation First, you need to install the `@redocly/cli` package. -You can install it [globally](/docs/cli/installation.md#install-globally) using npm or Yarn. +You can install it [globally](../../cli/installation.md#install-globally) using npm or Yarn. -Or you can install it during [runtime](/docs/cli/installation.md#use-npx-at-runtime) using npx or Docker. +Or you can install it during [runtime](../../installation.md#use-npx-at-runtime) using npx or Docker. ## Step 2 - Build the HTML file diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md index a824a66c..02aa5344 100644 --- a/docs/deployment/intro.md +++ b/docs/deployment/intro.md @@ -30,8 +30,8 @@ The following options are supported: You need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions: - OpenAPI 3.0 - - [Rebilly Users OpenAPI Definition](https://raw.githubusercontent.com/Rebilly/api-definitions/main/openapi/users.yaml) - - [Swagger Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json) + - [Museum Example API](https://github.com/Redocly/museum-openapi-example/blob/main/openapi.yaml) + - [Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json) - OpenAPI 2.0 - [Thingful OpenAPI Definition](https://raw.githubusercontent.com/thingful/openapi-spec/master/spec/swagger.yaml) - [Fitbit Plus OpenAPI Definition](https://raw.githubusercontent.com/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml) diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 5074cff3..8ee7d5c9 100644 --- a/docs/redoc-vendor-extensions.md +++ b/docs/redoc-vendor-extensions.md @@ -50,7 +50,7 @@ You can use the following [vendor extensions](https://redocly.com/docs/openapi-v - [x-explicitMappingOnly example](#x-explicitmappingonly-example) ## Swagger Object -Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi/) +Extends the OpenAPI root [OpenAPI Object](https://redocly.com/docs/openapi-visual-reference/openapi-1/) ### x-servers Backported from OpenAPI 3.0 [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject). Currently doesn't support templates. @@ -73,7 +73,7 @@ Information about tags group | Field Name | Type | Description | | :---------- | :--------: | :---------- | | name | string | The group name | -| tags | [ string ] | List of tags to include in this group +| tags | [ string ] | List of tags to include in this group | #### x-tagGroups example json @@ -148,10 +148,10 @@ The information about API logo #### Fixed fields | Field Name | Type | Description | | :-------------- | :------: | :---------- | -| url | string | The URL pointing to the spec logo. MUST be in the format of a URL. It SHOULD be an absolute URL so your API definition is usable from any location -| backgroundColor | string | background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) -| altText | string | Text to use for alt tag on the logo. Defaults to 'logo' if nothing is provided. -| href | string | The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS. +| url | string | The URL pointing to the spec logo. MUST be in the format of a URL. It SHOULD be an absolute URL so your API definition is usable from any location | +| backgroundColor | string | background color to be used. MUST be RGB color in [hexadecimal format] (https://en.wikipedia.org/wiki/Web_colors#Hex_triplet) | +| altText | string | Text to use for alt tag on the logo. Defaults to 'logo' if nothing is provided. | +| href | string | The URL pointing to the contact page. Default to 'info.contact.url' field of the OAS. | #### x-logo example