ci: Break CI build on broken links, ommitted files

Mkdocs is able to detect broken links or files ommitted from the "nav"
configuration, etc. By default, it reports them at the "INFO" level.
Instead, we can have "mkdocs build" report them as warnings. To do so,
we follow the documentation's "recommended settings for most sites
(maximal strictness)" (see link).

Once "mkdocs build" emits warnings for these issues, we can use the
strict mode (-s|--strict) to have the build error out if anything looks
wrong. Let's use this in CI to detect broken links, for example.

Link: https://www.mkdocs.org/user-guide/configuration/#validation
Signed-off-by: Quentin Monnet <qmo@qmon.net>

Author: qmonnet

.github/workflows/ci.yaml

@@ -31,7 +31,7 @@ jobs:
         uses: extractions/setup-just@v2
 
       - name: Build docs
-        run: just build
+        run: just build --strict
 
       - name: Deploy preview to Netlify
         uses: nwtgck/actions-netlify@v2

Justfile

@@ -14,7 +14,7 @@ _run +cmd:
   docker run -q --pull=always --rm -v $(pwd):/docs -p 8000:8000 {{image}} {{cmd}}
 
 # Build docs site (unversioned)
-build: (_run "mkdocs build")
+build *opts: (_run "mkdocs build" opts)
 
 # Clean generated docs site
 clean:

mkdocs.yml

@@ -133,6 +133,12 @@ markdown_extensions:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+
 watch:
   - includes
   - overrides