Add infrastructure to check Markdown files for problems

.github/workflows/check-markdown-task.yml

@@ -0,0 +1,117 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md
+name: Check Markdown
+
+env:
+  # See: https://github.com/actions/setup-node/#readme
+  NODE_VERSION: 16.x
+
+# See: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+on:
+  create:
+  push:
+    paths:
+      - ".github/workflows/check-markdown-task.ya?ml"
+      - ".markdown-link-check.json"
+      - "package.json"
+      - "package-lock.json"
+      - "Taskfile.ya?ml"
+      - "**/.markdownlint*"
+      - "**.mdx?"
+      - "**.mkdn"
+      - "**.mdown"
+      - "**.markdown"
+  pull_request:
+    paths:
+      - ".github/workflows/check-markdown-task.ya?ml"
+      - ".markdown-link-check.json"
+      - "package.json"
+      - "package-lock.json"
+      - "Taskfile.ya?ml"
+      - "**/.markdownlint*"
+      - "**.mdx?"
+      - "**.mkdn"
+      - "**.mdown"
+      - "**.markdown"
+  schedule:
+    # Run every Tuesday at 8 AM UTC to catch breakage caused by external changes.
+    - cron: "0 8 * * TUE"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  run-determination:
+    runs-on: ubuntu-latest
+    permissions: {}
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    steps:
+      - name: Determine if the rest of the workflow should run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="^refs/heads/v[0-9]+$"
+          # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
+          if [[
+            "${{ github.event_name }}" != "create" ||
+            "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
+          ]]; then
+            # Run the other jobs.
+            RESULT="true"
+          else
+            # There is no need to run the other jobs.
+            RESULT="false"
+          fi
+
+          echo "result=$RESULT" >> $GITHUB_OUTPUT
+
+  lint:
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Initialize markdownlint-cli problem matcher
+        uses: xt0rted/markdownlint-problem-matcher@v2
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Lint
+        run: task markdown:lint
+
+  links:
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Check links
+        run: task --silent markdown:check-links

.github/workflows/check-toc-task.yml

@@ -0,0 +1,93 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-toc-task.md
+name: Check ToC
+
+env:
+  # See: https://github.com/actions/setup-node/#readme
+  NODE_VERSION: 16.x
+
+# See: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+on:
+  create:
+  push:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      - "package.json"
+      - "package-lock.json"
+      - "README.md"
+  pull_request:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      - "package.json"
+      - "package-lock.json"
+      - "README.md"
+  schedule:
+    # Run periodically to catch breakage caused by external changes.
+    - cron: "0 3 * * WED"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  run-determination:
+    runs-on: ubuntu-latest
+    permissions: {}
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    steps:
+      - name: Determine if the rest of the workflow should run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="^refs/heads/v[0-9]+$"
+          # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
+          if [[
+            "${{ github.event_name }}" != "create" ||
+            "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
+          ]]; then
+            # Run the other jobs.
+            RESULT="true"
+          else
+            # There is no need to run the other jobs.
+            RESULT="false"
+          fi
+
+          echo "result=$RESULT" >> $GITHUB_OUTPUT
+
+  check:
+    name: ${{ matrix.file.name }}
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        file:
+          - name: README.md
+            # Max ToC depth, for use with the markdown-toc --maxdepth flag.
+            maxdepth: 4
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Rebuild ToC
+        run: |
+          task markdown:toc \
+            FILE_PATH="${{ github.workspace }}/${{ matrix.file.name }}" \
+            MAX_DEPTH=${{ matrix.file.maxdepth }}
+
+      - name: Check ToC
+        run: git diff --color --exit-code

.markdown-link-check.json

@@ -0,0 +1,13 @@
+{
+  "httpHeaders": [
+    {
+      "urls": ["https://docs.github.com/"],
+      "headers": {
+        "Accept-Encoding": "gzip, deflate, br"
+      }
+    }
+  ],
+  "retryOn429": true,
+  "retryCount": 3,
+  "aliveStatusCodes": [200, 206]
+}

.markdownlint.yml

@@ -0,0 +1,62 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlint.yml
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+# The code style defined in this file is the official standardized style to be used in all Arduino projects and should
+# not be modified.
+# Note: Rules disabled solely because they are redundant to Prettier are marked with a "Prettier" comment.
+
+default: false
+MD001: false
+MD002: false
+MD003: false # Prettier
+MD004: false # Prettier
+MD005: false # Prettier
+MD006: false # Prettier
+MD007: false # Prettier
+MD008: false # Prettier
+MD009:
+  br_spaces: 0
+  strict: true
+  list_item_empty_lines: false # Prettier
+MD010: false # Prettier
+MD011: true
+MD012: false # Prettier
+MD013: false
+MD014: false
+MD018: true
+MD019: false # Prettier
+MD020: true
+MD021: false # Prettier
+MD022: false # Prettier
+MD023: false # Prettier
+MD024: false
+MD025:
+  level: 1
+  front_matter_title: '^\s*"?title"?\s*[:=]'
+MD026: false
+MD027: false # Prettier
+MD028: false
+MD029:
+  style: one
+MD030:
+  ul_single: 1
+  ol_single: 1
+  ul_multi: 1
+  ol_multi: 1
+MD031: false # Prettier
+MD032: false # Prettier
+MD033: false
+MD034: false
+MD035: false # Prettier
+MD036: false
+MD037: true
+MD038: true
+MD039: true
+MD040: false
+MD041: false
+MD042: true
+MD043: false
+MD044: false
+MD045: true
+MD046:
+  style: fenced
+MD047: false # Prettier

.markdownlintignore

@@ -0,0 +1,4 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlintignore
+.licenses/
+__pycache__/
+node_modules/

README.md

@@ -1,9 +1,11 @@
 # `arduino/report-size-deltas` action
 
+[![Check Markdown status](https://github.com/arduino/report-size-deltas/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-markdown-task.yml)
 [![Check npm status](https://github.com/arduino/report-size-deltas/actions/workflows/check-npm-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-npm-task.yml)
 [![Check Poetry status](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml)
 [![Check Python status](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml)
 [![Check Taskfiles status](https://github.com/arduino/report-size-deltas/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-taskfiles.yml)
+[![Check ToC status](https://github.com/arduino/report-size-deltas/actions/workflows/check-toc-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-toc-task.yml)
 [![Integration Tests](https://github.com/arduino/report-size-deltas/actions/workflows/test-integration.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/test-integration.yml)
 [![Spell Check status](https://github.com/arduino/report-size-deltas/actions/workflows/spell-check-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/spell-check-task.yml)
 [![Sync Labels status](https://github.com/arduino/report-size-deltas/actions/workflows/sync-labels-npm.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/sync-labels-npm.yml)
@@ -37,15 +39,15 @@ This action comments on the pull request with a report on the resulting change i
 
 The action can be used in two ways:
 
-#### Run from a [scheduled workflow](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#onschedule)
+#### Run from a scheduled workflow
 
 Recommended for public repositories.
 
-The use of a scheduled workflow is necessary in order for the action to have the [write permissions required to comment on pull requests submitted from forks](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token).
+The use of a [scheduled workflow](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#onschedule) is necessary in order for the action to have the [write permissions required to comment on pull requests submitted from forks](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token).
 
 In this usage, the `sketches-reports-source` defines the name of the workflow artifact that contains the memory usage data, as specified to the [`actions/upload-artifact`](https://github.com/actions/upload-artifact) action via its `name` input.
 
-#### Run from the same workflow as the [`arduino/compile-sketches`](https://github.com/arduino/compile-sketches) action
+#### Run from the same workflow as the `arduino/compile-sketches` action
 
 Recommended for private repositories.