docs: add markdownlint and some link checks alongside vale

.github/workflows/docs-tests.yaml

@@ -0,0 +1,36 @@
+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: 'README.md' '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
+          version: 2.30.0
+
+  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

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