ci: add problem matcher for htmlproofer invalid url errors and fix build

.github/matcher-htmlproofer.json

@@ -0,0 +1,15 @@
+{
+  "__comment": "Docs: https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md",
+  "problemMatcher": [
+    {
+      "owner": "htmlproofer",
+      "pattern": [
+        {
+          "regexp": "^ERROR\\s+-\\s+htmlproofer: (invalid url - .+ \\[.+\\]) \\[(.+)\\]$",
+          "file": 2,
+          "message": 1
+        }
+      ]
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -84,6 +84,10 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
+      # https://github.com/actions/toolkit/blob/main/docs/commands.md#problem-matchers
+      - name: Add problem matcher for HTML proofer invalid url errors
+        run: |
+          echo "::add-matcher::.github/matcher-htmlproofer.json"
       - name: Build site
         run: uv run mkdocs build --strict
 

REUSE.toml

@@ -28,6 +28,14 @@ precedence = "override"
 SPDX-FileCopyrightText = "Copyright (C) 2022 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>"
 SPDX-License-Identifier = "MIT"
 
+[[annotations]]
+path = [
+    ".github/matcher-htmlproofer.json",
+]
+precedence = "override"
+SPDX-FileCopyrightText = "Copyright (C) 2026 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>"
+SPDX-License-Identifier = "MIT"
+
 [[annotations]]
 path = [
     ".vscode/C4.code-snippets",

docs/development/architecture/migration.md

@@ -33,7 +33,7 @@ More details about this pattern can be found in the resources below.
 - [The Strangler Fig Migration Pattern | by Diana Darie | Medium](https://dianadarie.medium.com/the-strangler-fig-migration-pattern-2e20a7350511)
 - [The Strangler pattern in practice - Michiel Rook's blog](https://www.michielrook.nl/2016/11/strangler-pattern-practice/)
 - [What is the Strangler Fig Pattern and How it Helps Manage Legacy Code](https://www.freecodecamp.org/news/what-is-the-strangler-pattern-in-software-development/)
-- [The Ship of Theseus to NOT rewrite a legacy system from scratch](https://web.archive.org/web/20241209060056/https://understandlegacycode.com/blog/ship-of-theseus-avoid-rewrite-legacy-system/)
+- [The Ship of Theseus to NOT rewrite a legacy system from scratch](https://understandlegacycode.com/blog/ship-of-theseus-avoid-rewrite-legacy-system/)
 - [https://docs.microsoft.com/en-us/azure/architecture/patterns/strangler-fig](https://docs.microsoft.com/en-us/azure/architecture/patterns/strangler-fig)
 
 ## Migration Process

docs/development/best_practices/code_review.md

@@ -172,6 +172,6 @@ The below list contains extra resources that may be of interest:
 
 [^talk]: Presentation and slides on "Code Review Skills for Pythonistas": https://www.nnja.io/post/2018/2018-djangocon-code-review/
 
-[^phauer]: Code Review Guidelines for Humans: https://phauer.com/2018/code-review-guidelines/
+[^phauer]: Code Review Guidelines for Humans: https://web.archive.org/web/20250623040639/https://phauer.com/2018/code-review-guidelines/
 
 [^twitter]: Rebecca's Rules for Constructive Code Reviews - Twitter: https://x.com/i_a_r_n_a/status/623922369376202758

mkdocs.yml

@@ -110,18 +110,15 @@ plugins:
   - privacy
   # https://github.com/manuzhang/mkdocs-htmlproofer-plugin#configuring
   - htmlproofer:
-      raise_error: True
+      # check all URLs before raising an error
+      raise_error_after_finish: True
       raise_error_excludes:
         # some URLs sporadically return a 504 (Gateway Timeout)
         504: ["*"]
         # sometimes URLs return a 429 (Too Many Requests)
         429: ["*"]
       skip_downloads: True
       ignore_urls:
-        # non-public URLs
-        - https://docs.opalmedapps.ca/*
-        - https://opalmedapps.gitlab.io/*
-        # - https://github.com/opalmedapps/*
         # PlantUML diagrams are included as data
         - "data:*"
         # Twitter URL sometimes returns a 404