chore: enable mkdocs-material-linter

Author: mschoettle

.github/workflows/ci.yml

@@ -53,6 +53,7 @@ jobs:
     uses: opalmedapps/.github/.github/workflows/markdownlint.yaml@main
     with:
       semantic-linebreak: false
+      mkdocs-material-linter: true
 
   build:
     runs-on: ubuntu-latest

.markdownlint.yml

@@ -39,3 +39,11 @@ max-one-sentence-per-line:
     - "!!"
     - "??"
     - "vs"
+
+# mkdocs-material-linter
+# see: https://github.com/mensfeld/mkdocs-material-linter?tab=readme-ov-file#provided-rules
+material-meta-tags: false
+# disabled due to code blocks with more than 3 backticks
+# https://github.com/mensfeld/mkdocs-material-linter/issues/24
+material-blank-lines-spacing: false
+material-code-block-syntax: false

docs/development/best_practices/best_practices.md

@@ -99,9 +99,7 @@ This can be done before making the change, after making the change or during.
 The tests should not only cover one (successful) code path but the goal is to achieve branch coverage and test for different inputs and error conditions.
 While you design your code, think about all the different ways this could be called, what should be considered and what could potentially go wrong (and test for those).
 
-!!! todo "TODO/TBD"
-
-    Integration tests, UI tests, smoke tests, …?
+<!-- TODO: Integration tests, UI tests, smoke tests, …? -->
 
 ## Continuous Integration (CI) and Delivery (CD)
 
@@ -175,9 +173,7 @@ This is easier to accomplish the smaller the changes are that a commit adds.
 In general, there are explicit merges, fast-forward merges and “squash on merge”.
 A great visualization of these is provided in the article [Pull Request Merge Strategies: The Great Debate - Atlassian Developer Blog](https://blog.developer.atlassian.com/pull-request-merge-strategies-the-great-debate/) and a debate on pros and cons can be found at [Git team workflows: merge or rebase? | Atlassian Git Tutorial](https://www.atlassian.com/git/articles/git-team-workflows-merge-or-rebase)
 
-!!! todo "TBD"
-
-    Use squash merge vs. merge commit
+<!-- TODO: Use squash merge vs. merge commit -->
 
 ### Merging Resources
 

docs/development/best_practices/diagrams.md

@@ -71,7 +71,7 @@ It is also possible to define a standalone file and include it within a page as
 
 The advantage of putting a diagram in its dedicated file is that the diagram is separated and can be automatically processed for other purposes.
 
-!!! important
+!!! info
 
     The plugin requires the full path within the repository to be specified.
     For this reason the recommendation is to place all diagrams within the directory under `docs/diagrams/`.

docs/development/guides/python.md

@@ -40,7 +40,3 @@ If not already done by an automatic dependency checker (see above), dependencies
 ## Django Migrations
 
 When writing migrations in Django that require custom Python code to be executed (using the RunPython migration), forward and backward code needs to be provided to ensure that the database can be migrated in both directions without encountering any errors.
-
-!!! todo "TBD"
-
-    Have a checker check for this (pylint has a plugin)

docs/install/integration.md

@@ -25,7 +25,7 @@ Depending on which Opal application is providing the endpoint, the authenticatio
 _OpalAdmin_ is built using [Django](https://www.djangoproject.com/) and uses the [Django REST Framework](https://www.django-rest-framework.org/) which provides support for token-based authentication.
 During the setup of the Opal PIE, an administrator can issue the hospital data system an API token which should be appended to the headers section of all API requests to _OpalAdmin_, for example:
 
-```bash
+```shell
 curl --location 'https://<host>/api/' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Token <token>'
@@ -38,15 +38,15 @@ _Legacy OpalAdmin_ will respond to successful calls at this endpoint with an arr
 Also included in the response will be a session/cookie string that should be appended to the headers of future requests to protected endpoints.
 For example:
 
-```bash
+```shell
 curl --location 'https://<host>/opalAdmin/user/system-login' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data 'username=<username>&password=<password>'
 ```
 
 Handle the response and append the cookie string to the next request:
 
-```bash
+```shell
 curl --location 'https://<host>/opalAdmin/patient/get/patient-exist' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --header 'Cookie: sessionId=<sessionid>' \
@@ -61,20 +61,20 @@ You can use "Basic Authentication" at the reverse proxy level (`traefik`).
 Use the `htpasswd` utility to create a bcrypt hash, pressing enter when given the opportunity to enter an additional password for the hash.
 For example:
 
-```bash
+```shell
 echo $(htpasswd -nB integration_engine) | sed -e s/\\$/\\$\\$/g
 ```
 
 The username and password used in the Basic Authentication header request from the hospital integration engine needs to be base64 encoded.
 So:
 
-```bash
+```shell
 echo -n 'integration_engine:<hash>' | base64
 ```
 
 The base64 representation of the username:password can then be added as an authorization header in the destination connector settings for our labs channel, prepended by the string `Basic` to indicate the auth type.
 
-```bash
+```shell
 --header 'Authorization Basic <value>'
 ```