ci: Improve docs website jobs

.github/workflows/gh-pages.yaml

@@ -18,7 +18,36 @@ env:
     TERM: xterm
 
 jobs:
-    deploy:
+    check-markdown:
+        name: "Lint Markdown"
+        runs-on: "ubuntu-22.04"
+        timeout-minutes: 1
+        steps:
+            -
+                name: "Checkout repository"
+                uses: "actions/[email protected]"
+            -
+                name: "Check Markdown formatting"
+                uses: "DavidAnson/[email protected]"
+                with:
+                    globs: "**/*.md"
+
+    check-links:
+        name: "Lint Links"
+        runs-on: "ubuntu-22.04"
+        timeout-minutes: 10
+        steps:
+            -
+                name: "Checkout repository"
+                uses: "actions/[email protected]"
+            -
+                name: "Run Lychee"
+                uses: "lycheeverse/[email protected]"
+                with:
+                    output: "${{ runner.temp }}/lychee/out.md"
+                    fail: true
+
+    build:
         runs-on: ubuntu-latest
         name: Deploy website
         permissions:
@@ -54,8 +83,45 @@ jobs:
             -   name: Rebuild website
                 run: make _website_build
 
+            -   uses: actions/upload-artifact@v3
+                name: Upload the docs artifact
+                with:
+                    name: docs-website
+                    path: dist/website
+
+    # This is a "trick", a meta task which does not change, and we can use in
+    # the protected branch rules as opposed to the tests one above which
+    # may change regularly.
+    validate-docs:
+        name: Docs status
+        runs-on: ubuntu-latest
+        needs:
+            - check-markdown
+            - check-links
+            - build
+        if: always()
+        steps:
+            - name: Successful run
+              if: ${{ !(contains(needs.*.result, 'failure')) }}
+              run: exit 0
+
+            - name: Failing run
+              if: ${{ contains(needs.*.result, 'failure') }}
+              run: exit 1
+
+    deploy:
+        runs-on: ubuntu-latest
+        name: Deploy website
+        permissions:
+            contents: write
+        steps:
+            -   uses: actions/download-artifact@v3
+                with:
+                    name: docs-website
+                    path: dist/website
+
             -   name: Deploy
                 uses: peaceiris/actions-gh-pages@v3
                 with:
                     github_token: ${{ secrets.GITHUB_TOKEN }}
-                    publish_dir: ./dist/website
+                    publish_dir: dist/website