Add infrastructure for maintaining the table of contents

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

@@ -0,0 +1,90 @@
+# 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
+    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/[0-9]+.[0-9]+.x"
+          # 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
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        file:
+          - name: README.md
+            # Max ToC depth, for use with the markdown-toc --maxdepth flag.
+            maxdepth: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        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

README.md

@@ -9,6 +9,7 @@
 [![Check Prettier Formatting status](https://github.com/arduino/compile-sketches/actions/workflows/check-prettier-formatting-task.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/check-prettier-formatting-task.yml)
 [![Check Python status](https://github.com/arduino/compile-sketches/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/check-python-task.yml)
 [![Check Taskfiles status](https://github.com/arduino/compile-sketches/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/check-taskfiles.yml)
+[![Check ToC status](https://github.com/arduino/compile-sketches/actions/workflows/check-toc-task.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/check-toc-task.yml)
 [![Spell Check status](https://github.com/arduino/compile-sketches/actions/workflows/spell-check-task.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/spell-check-task.yml)
 [![Sync Labels status](https://github.com/arduino/compile-sketches/actions/workflows/sync-labels-npm.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/sync-labels-npm.yml)
 [![Test Python status](https://github.com/arduino/compile-sketches/actions/workflows/test-python-poetry-task.yml/badge.svg)](https://github.com/arduino/compile-sketches/actions/workflows/test-python-poetry-task.yml)

Taskfile.yml

@@ -25,6 +25,10 @@ tasks:
       - task: general:correct-spelling
       - task: general:format-prettier
       - task: markdown:fix
+      - task: markdown:toc
+        vars:
+          FILE_PATH: README.md
+          MAX_DEPTH: 5
       - task: python:format
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-action-metadata-task/Taskfile.yml
@@ -266,6 +270,19 @@ tasks:
     cmds:
       - npx markdownlint-cli "**/*.md"
 
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-toc-task/Taskfile.yml
+  markdown:toc:
+    desc: Update the table of contents
+    deps:
+      - task: npm:install-deps
+    cmds:
+      - |
+        npx markdown-toc \
+            --bullets=- \
+            --maxdepth={{.MAX_DEPTH}} \
+            -i \
+            "{{.FILE_PATH}}"
+
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
   npm:install-deps:
     desc: Install dependencies managed by npm