build: Add more docs checks (#1149)

.github/workflows/gh-pages.yaml

@@ -8,6 +8,11 @@ on:
             - doc/**
             - mkdocs.yaml
             - .github/workflows/gh-pages.yaml
+    pull_request:
+        paths:
+            - doc/**
+            - mkdocs.yaml
+            - .github/workflows/gh-pages.yaml
 
 # See https://stackoverflow.com/a/72408109
 concurrency:
@@ -18,9 +23,45 @@ env:
     TERM: xterm
 
 jobs:
-    deploy:
+    check-markdown:
+        name: Lint Markdown
         runs-on: ubuntu-latest
-        name: Deploy website
+        timeout-minutes: 1
+        steps:
+            -   name: Checkout repository
+                uses: actions/checkout@v3
+
+            -   name: Check Markdown formatting
+                uses: DavidAnson/[email protected]
+                with:
+                    globs: "*.md|docs/**/*.md"
+
+    check-links:
+        name: Lint Links
+        runs-on: ubuntu-latest
+        timeout-minutes: 1
+        steps:
+            -   name: Checkout repository
+                uses: actions/checkout@v3
+
+            -   name: Restore lychee cache
+                uses: actions/cache@v3
+                with:
+                    path: .lycheecache
+                    key: cache-lychee-${{ github.sha }}
+                    restore-keys: cache-lychee-
+
+            -   name: Run Lychee
+                uses: lycheeverse/[email protected]
+                with:
+                    # To keep in sync with Makefile#lychee
+                    args: "--verbose --no-progress '*.md' 'docs/**/*.md' --cache --max-cache-age 1d ."
+                    output: ${{ runner.temp }}/lychee/out.md
+                    fail: true
+
+    build:
+        runs-on: ubuntu-latest
+        name: Build docs
         permissions:
             contents: write
         steps:
@@ -54,8 +95,46 @@ 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
+        if: github.ref == 'refs/heads/main'
+        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

.markdownlint.jsonc

@@ -0,0 +1,10 @@
+{
+    "MD007": false,
+    "MD012": false,
+    "MD013": false,
+    "MD024": false,
+    "MD029": false,
+    "MD033": false,
+    "MD034": false,
+    "MD041": false,
+}

Makefile

@@ -284,6 +284,22 @@ blackfire: $(SCOPED_BOX_BIN)
 # Website rules
 #---------------------------------------------------------------------------
 
+.PHONY: website_check
+website_check:		 ## Runs various checks for the website
+website_check: markdownlint lychee website_build
+
+.PHONY: markdownlint
+markdownlint:
+	@echo "$(YELLOW_COLOR)Ensure you have the nodejs & npm installed. For more information, check:$(NO_COLOR)"
+	@# To keep in sync with .github/workflows/gh-pages.yaml#check-links
+	npx markdownlint-cli2 "*.md|docs/**/*.md"
+
+.PHONY: lychee
+lychee:
+	@echo "$(YELLOW_COLOR)Ensure you have the lychee command installed. For more information, check:$(NO_COLOR)"
+	@echo "https://github.com/lycheeverse/lychee"
+	@# To keep in sync with .github/workflows/gh-pages.yaml#check-links
+	lychee --verbose --no-progress '*.md' 'docs/**/*.md'
 
 .PHONY: website_build
 website_build:		 ## Builds the website

tests/AutoReview/MakefileTest.php

@@ -51,6 +51,7 @@ protected function getExpectedHelpOutput(): string
             phpunit_coverage_html:       Runs PHPUnit with code coverage with HTML report
             phpunit_coverage_infection:  Runs PHPUnit tests with test coverage
             blackfire:		  Profiles the compile step
+            website_check:		  Runs various checks for the website
             website_build:		  Builds the website
             website_serve:		  Serves the website locally