Add Markdown documentation linting

.githooks/pre-commit

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+if ! command -v rumdl >/dev/null 2>&1; then
+  echo "Error: rumdl not found. Please install using requirements-dev.txt" >&2
+  exit 1
+fi
+
+rumdl check --config .rumdl.toml --respect-gitignore --exclude "build,**/build" .

.github/workflows/basic.yml

@@ -34,6 +34,19 @@ jobs:
       - name: Validate CBOM
         run: scripts/validate_cbom.sh
 
+  markdownlint:
+    name: Check Markdown documentation
+    needs: [workflowcheck]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # pin@v4
+      - name: Install rumdl
+        run: |
+          python3 -m pip install --user -r requirements-dev.txt
+      - name: Ensure Markdown conventions are upheld
+        run: ~/.local/bin/rumdl check --config .rumdl.toml --respect-gitignore --exclude "build,**/build" .
+
   upstreamcheck:
     name: Check upstream code is properly integrated
     needs: [workflowcheck]

.rumdl.toml

@@ -0,0 +1,25 @@
+[global]
+# Keep the initial lint configuration focused on Markdown rules that match the
+# existing documentation style and do not require unrelated documentation churn.
+enable = [
+  "MD001", # heading-increment
+  "MD004", # ul-style
+  "MD011", # no-reversed-links
+  "MD014", # commands-show-output
+  "MD018", # no-missing-space-atx
+  "MD019", # no-multiple-space-atx
+  "MD020", # no-missing-space-closed-atx
+  "MD021", # no-multiple-space-closed-atx
+  "MD023", # heading-start-left
+  "MD026", # no-trailing-punctuation
+  "MD027", # no-multiple-space-blockquote
+  "MD028", # no-blanks-blockquote
+  "MD035", # hr-style
+  "MD037", # no-space-in-emphasis
+  "MD039", # no-space-in-links
+  "MD042", # no-empty-links
+  "MD043", # required-headings
+  "MD044", # proper-names
+  "MD045", # no-alt-text
+  "MD048", # code-fence-style
+]

CONTRIBUTING.md

@@ -45,6 +45,19 @@ LIBOQS_DIR=<liboqs directory> ./scripts/format_code.sh
 ```
 This script has been tested on x86\_64 Ubuntu and arm64 macOS. Contributions for other platforms are welcome and appreciated!
 
+### Git hooks
+
+This project uses git hooks to automatically run linters and formatters. Git
+hooks are stored under `.githooks/`. After cloning this repository, you can
+point git to use these hooks by setting `core.hooksPath`:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+> `core.hooksPath` is available in git 2.9 or newer; for older versions of git,
+> please manually set up symlinks or copy the hooks into `.git/hooks`.
+
 ### Public and internal APIs
 
 Public API functions are marked with the `OQS_API` keyword. These functions are made available to users of the library.

requirements-dev.txt

@@ -0,0 +1,8 @@
+rumdl==0.2.18 \
+  --hash=sha256:796720b8756baeebf9a976be0cf619441aa7757e72dd9832f62b752b72f70cdd \
+  --hash=sha256:c9c033a722f64b71093c30f795587184321641d612354d1ead75d0145f970148 \
+  --hash=sha256:aef55096d0320227fa07bbac049190b63c4a856cfbccee5286517e67c942d6ef \
+  --hash=sha256:78bdd91166fa54c30ff1f83648fb1f371b5f25534eb4ec9e0c997b649996faa6 \
+  --hash=sha256:c7721883781adfcca7204f2a9d45deacd7a663b0402fb043c240f5b90f36c113 \
+  --hash=sha256:fe5c778e7b3e0a0ac5cca891c0668be649a9d228b6d231ed7f59b5726929457e \
+  --hash=sha256:17e21e25ee8c95e7a7881585e28eb52c8ccb6c18bda3707eef475b0e221debcc