Merge pull request #22 from per1234/check-toc

Add template workflow to check for missed updates to Markdown ToC

Author: per1234

workflow-templates/assets/check-toc-task/Taskfile.yml

@@ -0,0 +1,14 @@
+# See: https://taskfile.dev/#/usage
+version: "3"
+
+tasks:
+  # 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
+    cmds:
+      - |
+        npx markdown-toc \
+            --bullets=- \
+            --maxdepth={{.MAX_DEPTH}} \
+            -i \
+            "{{.FILE_PATH}}"

workflow-templates/check-toc-task.md

@@ -0,0 +1,49 @@
+# "Check ToC" workflow (Task)
+
+Workflow file: [check-toc-task.yml](check-toc-task.yml)
+
+Check whether the generated table of contents in Markdown files matches their heading structure.
+
+This should be used in repositories that generate the table of contents with [markdown-toc](https://github.com/jonschlinkert/markdown-toc).
+
+This is the version of the workflow for projects using the [Task](https://taskfile.dev/#/) task runner tool.
+
+## Assets
+
+- [`Taskfile.yml`](assets/check-toc-task/Taskfile.yml] - Formatting task.
+  - Install to: repository root (or add the `markdown:toc` task into the existing `Taskfile.yml`)
+
+## Readme badge
+
+Markdown badge:
+
+```markdown
+[![Check ToC status](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/check-toc-task.yml/badge.svg)](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/check-toc-task.yml)
+```
+
+Replace the `REPO_OWNER` and `REPO_NAME` placeholders in the URLs with the final repository owner and name ([example](https://raw.githubusercontent.com/arduino-libraries/ArduinoIoTCloud/master/README.md)).
+
+---
+
+Asciidoc badge:
+
+```adoc
+image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-toc-task.yml/badge.svg["Check ToC status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-toc-task.yml"]
+```
+
+Define the `{repository-owner}` and `{repository-name}` attributes and use them throughout the readme ([example](https://raw.githubusercontent.com/arduino-libraries/WiFiNINA/master/README.adoc)).
+
+## Commit message
+
+```
+Add CI workflow to check for missed updates to readme ToC
+
+On every push or pull request that affects the repository's README.md, check whether the table of contents matches the
+content.
+```
+
+## PR message
+
+```markdown
+On every push or pull request that affects the repository's README.md, use [markdown-toc](https://github.com/jonschlinkert/markdown-toc) to check whether the table of contents matches the content.
+```

workflow-templates/check-toc-task.yml

@@ -0,0 +1,51 @@
+# Source: https://github.com/arduino/.github/blob/master/workflow-templates/check-toc-task.md
+name: Check ToC
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      # TODO: Update this if ToC of any other files should be checked.
+      - "README.md"
+  pull_request:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      # TODO: Update this if ToC of any other files should be checked.
+      - "README.md"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  check:
+    name: ${{ matrix.file.name }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        file:
+          # TODO: Update this if any other files should be checked.
+          - name: README.md
+            # Max ToC depth, for use with the markdown-toc --maxdepth flag.
+            maxdepth: 3
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - 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

workflow-templates/dependabot/workflow-template-copies/.github/workflows/check-toc-task.yml

@@ -0,0 +1,51 @@
+# Source: https://github.com/arduino/.github/blob/master/workflow-templates/check-toc-task.md
+name: Check ToC
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      # TODO: Update this if ToC of any other files should be checked.
+      - "README.md"
+  pull_request:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      # TODO: Update this if ToC of any other files should be checked.
+      - "README.md"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  check:
+    name: ${{ matrix.file.name }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        file:
+          # TODO: Update this if any other files should be checked.
+          - name: README.md
+            # Max ToC depth, for use with the markdown-toc --maxdepth flag.
+            maxdepth: 3
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - 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