Split make linkcheck out into a distinct job [#106]

Also add `continue-on-error-comment` step, so that if linkcheck fails,
a comment will be added to the PR, instead of a silent failure with a
green check.

.github/workflows/docs-ci.yaml

@@ -39,6 +39,8 @@ on:
         type: string
         default: html
 
+permissions:
+  pull-requests: write
 env:
   # Used for `make` steps.
   # -n: warn on missing references
@@ -68,9 +70,6 @@ jobs:
       - run: make ${{ inputs.make-target }}
         working-directory: ${{ inputs.docs-directory }}
 
-      - run: make linkcheck
-        working-directory: ${{ inputs.docs-directory }}
-
   build-pip:
     if: inputs.pip-install-target != ''
     runs-on: ubuntu-latest
@@ -86,5 +85,22 @@ jobs:
       - run: make ${{ inputs.make-target }}
         working-directory: ${{ inputs.docs-directory }}
 
-      - run: make linkcheck
+  linkcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ inputs.repo }}
+
+      - run: pip install '${{ inputs.pip-install-target }}'
+
+      - id: linkcheck
+        run: make linkcheck
         working-directory: ${{ inputs.docs-directory }}
+        continue-on-error: true
+
+      - uses: mainmatter/continue-on-error-comment@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          outcome: ${{ steps.linkcheck.outcome }}
+          test-id: Linkcheck error: ${{ matrix.code }}