Upload corrected files to workflow artifact if ToC is outdated

Some assets contain a table of contents to facilitate the navigation of their content.

The table of contents must be kept in sync with the content. The continuous integration system uses the excellent
markdown-toc tool to detect outdated table of contents.

In order to support checking any number of files at arbitrary paths in the repository, using a specified `--maxdepth`
flag value for each, a job matrix is used in the "Check ToC" GitHub Actions workflow. The user may also run the
`markdown:toc` locally to update the table of contents, but because the project-specific configuration is implemented in
the workflow instead of the taskfile they must specify the file's path and `--maxdepth` flag value via task variables in
the invocation. Contributors may find it challenging to update the table of contents.

In order to facilitate the update following detection of an out of sync state by the continuous integration system, the
corrected file is uploaded to a workflow artifact. The contributor can download the workflow artifact and replace the
out of sync file with the corrected version.

Author: per1234

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

@@ -56,6 +56,9 @@ jobs:
     if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
 
+    env:
+      ARTIFACT_NAME: corrected-files
+
     strategy:
       fail-fast: false
 
@@ -86,4 +89,20 @@ jobs:
             MAX_DEPTH=${{ matrix.file.maxdepth }}
 
       - name: Check ToC
+        id: check-toc
         run: git diff --color --exit-code
+
+      - name: Upload corrected file to workflow artifact
+        if: failure() && steps.check-toc.outcome == 'failure'
+        uses: actions/upload-artifact@v3
+        with:
+          if-no-files-found: error
+          name: ${{ env.ARTIFACT_NAME }}
+          # Globstar prefix is to preserve folder structure in artifact.
+          # https://github.com/actions/upload-artifact/tree/v3.1.2#:~:text=path%20hierarchy%20will%20be%20preserved
+          path: "**/${{ matrix.file.name }}"
+
+      - name: Add artifact availability notice
+        if: failure() && steps.check-toc.outcome == 'failure'
+        run: |
+          echo "::notice file=${{ matrix.file.name }}::Corrected file was saved to the ${{ env.ARTIFACT_NAME }} workflow artifact"

Taskfile.yml

@@ -20,7 +20,6 @@ tasks:
       - task: general:correct-spelling
       - task: general:format-prettier
       - task: markdown:fix
-      - task: markdown:toc
 
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-workflows-task/Taskfile.yml
   ci:validate: