From 2f9bf529a4b317f3c3e3565fe9ec9dc728fff498 Mon Sep 17 00:00:00 2001 From: Quentin Monnet Date: Thu, 3 Apr 2025 12:22:45 +0100 Subject: [PATCH] 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 --- .github/workflows/ci.yaml | 2 +- Justfile | 2 +- mkdocs.yml | 6 ++++++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 12349610..45fc4b4c 100644 --- a/.github/workflows/ci.yaml +++ b/.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 diff --git a/Justfile b/Justfile index fb0d8dbb..c4dc2648 100644 --- a/Justfile +++ b/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: diff --git a/mkdocs.yml b/mkdocs.yml index d509f9d1..38bdf292 100644 --- a/mkdocs.yml +++ b/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