Add Markdown documentation linting

.github/pull_request_template.md

@@ -12,4 +12,3 @@
 <!-- If this contribution (code, documentation, descriptive text) was produced with the help of generative AI, please describe the nature of the use. Contributors are expected to have verified and affirm such contributions themselves before submission. -->
 
 <!-- Once your pull request is ready for review and passing continuous integration tests, please convert from a draft PR to a normal PR, and request a review from one of the OQS core team members. -->
-

.github/workflows/basic.yml

@@ -34,6 +34,16 @@ 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: Ensure Markdown conventions are upheld
+        run: npx --yes markdownlint-cli2@0.22.1 --config .markdownlint.yml "**/*.md" "#build" "#**/build" "#src"
+
   upstreamcheck:
     name: Check upstream code is properly integrated
     needs: [workflowcheck]

.markdownlint.yml

@@ -0,0 +1,42 @@
+default: true
+
+# The project documentation intentionally contains long lines, HTML anchors,
+# bare URLs, and generated tables whose anchors are consumed by GitHub and
+# Doxygen. Keep the lint configuration focused on broadly applicable Markdown
+# structure checks that match the existing documentation style.
+#
+# Vendored upstream Markdown under src/** is excluded by the lint command
+# rather than here, since the ignore lives in the file-selection glob.
+#
+# Trailing comments give current violation count / files affected if the rule
+# were enabled (measured against the in-tree Markdown). Rules without a count
+# are already enabled. Tags after the count flag rules that need extra care:
+#   [skip]      do not enable — fundamentally incompatible with project style
+#               or with Doxygen rendering of README.md/CONFIGURE.md/SECURITY.md
+#   [needs prep] can be enabled, but only after addressing a specific blocker
+MD003: false # heading-style                   (42 violations / 2 files)
+MD007: false # ul-indent                       (79 violations / 16 files)
+MD009: false # no-trailing-spaces              (37 violations / 9 files) [needs prep: CONFIGURE.md is Doxygen-consumed and has 10 trailing-double-space lines that may be intentional Markdown hard breaks; audit before stripping]
+MD010: true  # no-hard-tabs
+MD012: true  # no-multiple-blanks
+MD013: false # line-length                     (1009 violations / 41 files) [skip: stylistic, no functional benefit, would require reflowing every paragraph and table]
+MD022: true  # blanks-around-headings
+MD024:       # no-duplicate-heading            — allow duplicates under different parent headings (GOVERNANCE.md, PLATFORMS.md repeat section names like "Tier 1" / "Maintainers" under different top-level sections)
+  siblings_only: true
+MD025: false # single-title                    (1 violation / 1 file) [needs prep: RELEASE.md uses two h1s ("# liboqs version" then "# Release notes"); demoting the second would change Doxygen anchors and possibly external links]
+MD029: false # ol-prefix                       (4 violations / 1 file) [needs prep: README.md Quickstart list is split by paragraph breaks; would require restructuring the section]
+MD030: true  # list-marker-space
+MD031: true  # blanks-around-fences
+MD032: true  # blanks-around-lists
+MD033: false # no-inline-html                  (57 violations / 20 files) [skip: inline HTML is load-bearing in CI.md and docs/algorithms/*.md for layout pure Markdown can't express]
+MD034: false # no-bare-urls                    (92 violations / 24 files) [skip: bare URLs auto-linkify in both GitHub-flavored Markdown and Doxygen; wrapping them in <> is purely cosmetic]
+MD036: true  # no-emphasis-as-heading
+MD038: true  # no-space-in-code
+MD040: true  # fenced-code-language
+MD041: false # first-line-heading              (2 violations / 2 files after src/** excluded) [needs prep: .github/pull_request_template.md is a checklist with no top-level heading by design; review whether to enforce]
+MD046: true  # code-block-style
+MD047: false # single-trailing-newline         (17 violations / 17 files) [needs prep: all 17 are auto-generated docs/algorithms/*.md; fix belongs in the generator, not the files]
+MD051: false # link-fragments                  (33 violations / 3 files) [skip: Doxygen preserves heading-case in anchors but markdownlint demands GitHub-slug lowercase; CONFIGURE.md is Doxygen-consumed and uses uppercase fragments deliberately]
+MD058: true  # blanks-around-tables
+MD059: false # descriptive-link-text           (only in vendored src/, now excluded)
+MD060: true  # table-column-style

CI.md

@@ -16,6 +16,7 @@ They implement the logic dictating which tests should run on which events.
 
 This workflow is triggered by pushes to non-`main` branches.
 It calls only [basic checks](#basic.yml) unless one of the following strings is included in the commit message:
+
 - "[full tests]": calls [all platform tests](#platforms.yml).
 - "[extended tests]": calls the [extended tests](#extended.yml).
 - "[trigger downstream]": calls the [downstream release tests](#downstream-release.yml).
@@ -61,6 +62,7 @@ This workflow runs code coverage tests and uploads the results to [Coveralls.io]
 
 These workflows contain tests for the individual [platforms supported by liboqs](PLATFORMS.md).
 Currently, these include
+
 - `android.yml`,
 - `apple.yml`,
 - `macos.yml`,
@@ -83,6 +85,7 @@ Currently, this includes constant-time testing with valgrind and the full suite
 
 This workflow triggers basic CI for a selection of projects that depend on `liboqs`.
 Currently, these include
+
 - [`OQS OpenSSL3 provider`](https://github.com/open-quantum-safe/oqs-provider)
 - [`OQS-BoringSSL`](https://github.com/open-quantum-safe/boringssl)
 - [`OQS-OpenSSH`](https://github.com/open-quantum-safe/openssh)

CONFIGURE.md

@@ -49,6 +49,7 @@ Can be set to the following values:
 **Default**: `Release` for single-configuration generators (Ninja, Makefile). Multi-configuration generators (Visual Studio, Xcode, Ninja Multi-Config) ignore `CMAKE_BUILD_TYPE` and instead select the configuration at build time via `--config`.
 
 **Examples**:
+
 ```bash
 # Defaults to CMAKE_BUILD_TYPE=Release
 cmake -GNinja ..
@@ -129,6 +130,7 @@ To save size and limit the amount of different cryptographic code bases, it is p
 This can be set to `ON` or `OFF`. When `ON`, the additional options `OQS_USE_AES_OPENSSL`, `OQS_USE_SHA2_OPENSSL`, and `OQS_USE_SHA3_OPENSSL` are made available to control whether liboqs uses OpenSSL's AES, SHA-2, and SHA-3 implementations.
 
 By default,
+
 - `OQS_USE_AES_OPENSSL` is `ON` (on x86-64 only if `OQS_DIST_BUILD` and `OQS_USE_AES_INSTRUCTIONS` are not set)
 - `OQS_USE_SHA2_OPENSSL` is `ON`
 - `OQS_USE_SHA3_OPENSSL` is `OFF`.
@@ -195,6 +197,7 @@ The OQS team explicitly discourages enabling this variable and reserves the righ
 It remains present as long as it is responsibly used as per the stated warnings.
 
 By default,
+
 - `OQS_ENABLE_SIG_STFL_XMSS` is `OFF` 
 - `OQS_ENABLE_SIG_STFL_LMS` is `OFF`
 - `OQS_HAZARDOUS_EXPERIMENTAL_ENABLE_SIG_STFL_KEY_SIG_GEN` is `OFF`.
@@ -204,6 +207,7 @@ By default,
 ## OQS_OPT_TARGET
 
 An optimization target. Only has an effect if the compiler is GCC or Clang and `OQS_DIST_BUILD=OFF`. Can take any valid input to the `-march` (on x86-64) or `-mcpu` (on ARM32v7 or ARM64v8) option for `CMAKE_C_COMPILER`. Can also be set to one of the following special values.
+
   - `auto`: Use `-march=native` or `-mcpu=native` (if the compiler supports it).
   - `generic`: Use `-march=x86-64` on x86-64, or `-mcpu=cortex-a5` on ARM32v7, or `-mcpu=cortex-a53` on ARM64v8.
 
@@ -273,6 +277,7 @@ Upstream projects can provide memory-optimized implementations by adding a separ
 **Default**: `OFF`.
 
 ## OQS_LIBJADE_BUILD
+
 Can be `ON` or `OFF`. When `ON` liboqs is built to use high assurance implementations of cryptographic algorithms from [Libjade](https://github.com/formosa-crypto/libjade). The cryptographic primitives in Libjade are written using [Jasmin](https://github.com/jasmin-lang/jasmin) and built using the Jasmin compiler. The Jasmin compiler is proven (in Coq) to preserve semantic correctness of a program, maintain secret-independence of control flow, and maintain secret independence of locations of memory access through compilation. Additionally, the Jasmin compiler guarantees thread safety because Jasmin doesn't support global variables. 
 
 At the moment, Libjade only provides Kyber512 and Kyber768 KEMs. 
@@ -288,6 +293,7 @@ Note: `ALG` in `OQS_ENABLE_LIBJADE_KEM_ALG/OQS_ENABLE_LIBJADE_SIG_ALG` should be
 **Default**: `OFF` if OQS_LIBJADE_BUILD is `OFF` else unset.
 
 ## OQS_BUILD_FUZZ_TESTS
+
 Can be `ON` or `OFF`. When `ON` liboqs the fuzz test-suite will be enabled. This option is only available if the c compiler is set to clang i.e. `-DCMAKE_C_COMPILER=clang`.
 
 Note: It is strongly recommended that this configuration be enabled with `CFLAGS=-fsanitize=address,fuzzer-no-link LDFLAGS=-fsanitize=address`. While fuzzing will run without these flags, enabling this instrumentation will make fuzzing performance much faster and catch [potential memory related bugs](https://clang.llvm.org/docs/AddressSanitizer.html). 

CONTRIBUTING.md

@@ -40,9 +40,11 @@ of the library as documented in the [style template](.astylerc).
 The `astyle` tool is used to check formatting in CI.
 Due to variations in behaviour across version and platforms, it is possible to encounter CI failures even if code has been locally formatted with `astyle`.
 To assist with this inconvenience, we provide a convenience script which runs `astyle` in the same Docker image that we use for the CI checks:
+
 ```bash
 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!
 
 ### Public and internal APIs
@@ -71,10 +73,12 @@ Other trigger strings are documented in [CI.md](CI.md#push.yml).
 [Act](https://github.com/nektos/act) is a tool facilitating local execution of
 GitHub CI jobs. When executed in the main `liboqs` directory, 
 
-    act -l Displays all GitHub CI jobs
-    act -j some-job Executes "some-job"
+```bash
+act -l         # Displays all GitHub CI jobs
+act -j some-job  # Executes "some-job"
+```
 
-When installing `act` as a GitHub extension, prefix the commands with `gh `.
+When installing `act` as a GitHub extension, prefix the commands with `gh`.
 
 ## Modifications to CI
 
@@ -90,6 +94,12 @@ or running the CI locally (as above):
 act workflow_call -W '.github/workflows/basic.yml'
 ```
 
+Markdown documentation is checked with [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) during the [basic.yml](.github/workflows/basic.yml) job, using the rules in [.markdownlint.yml](.markdownlint.yml). Changes to Markdown files can be validated locally with the same command CI runs:
+
+```bash
+npx --yes markdownlint-cli2@0.22.1 --config .markdownlint.yml "**/*.md" "#build" "#**/build" "#src"
+```
+
 ### New features
 
 Any PR introducing a new feature is expected to contain a test of this feature