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

@@ -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

.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

.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"

README.md

@@ -1,11 +1,11 @@
 <div align="center">
   <img alt="Redoc logo" src="https://raw.githubusercontent.com/Redocly/redoc/main//docs/images/redoc.png" width="400px" />
 
-  # 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)
 </div>
 
 
@@ -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) <br>
-  ![](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 
 ```
 

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`.

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
 

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)

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