Build the wolfCOSE manual with the shared documentation tooling

.github/workflows/docs-site.yml

@@ -0,0 +1,73 @@
+name: Build manual with documentation tooling
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'tools/docs_manual.py'
+      - 'tools/docs-manual/**'
+      - 'docker/docs/**'
+      - '.github/workflows/docs-site.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'tools/docs_manual.py'
+      - 'tools/docs-manual/**'
+      - 'docker/docs/**'
+      - '.github/workflows/docs-site.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - name: Select documentation revision
+        id: documentation
+        run: echo "sha=$(cat tools/docs-manual/documentation-rev)" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v4
+        with:
+          repository: wolfSSL/documentation
+          ref: ${{ steps.documentation.outputs.sha }}
+          path: build/documentation
+          submodules: recursive
+          persist-credentials: false
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Pull documentation builder
+        run: |
+          set -euo pipefail
+          image_sha=$(sha256sum docker/docs/Dockerfile docker/docs/requirements.txt | sha256sum | cut -c1-16)
+          image="ghcr.io/wolfssl/wolfcose-docs:sha-$image_sha"
+          if ! docker pull "$image"; then
+            docker build --pull -t "$image" docker/docs
+          fi
+          echo "DOCS_IMAGE=$image" >> "$GITHUB_ENV"
+      - name: Build and validate HTML and PDF
+        run: |
+          tools/check-docs-no-internal-links.sh
+          docker run --rm --user "$(id -u):$(id -g)" --env HOME=/tmp \
+            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/work/wolfCOSE" \
+            --workdir /work/wolfCOSE "$DOCS_IMAGE" \
+            sh -c 'python3 tools/docs_manual.py build --documentation-root /work/wolfCOSE/build/documentation --source-root /work/wolfCOSE --target all && cd build/documentation/wolfCOSE && mkdocs build --strict -f mkdocs.yml'
+          test -s build/documentation/wolfCOSE/html/index.html
+          test -s build/documentation/wolfCOSE/wolfCOSE-Manual.pdf
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wolfcose-manual
+          path: |
+            build/documentation/wolfCOSE/html/
+            build/documentation/wolfCOSE/wolfCOSE-Manual.pdf
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/misra-2023.yml

@@ -206,8 +206,7 @@ jobs:
     - name: Run clang-tidy
       run: |
         export WOLFSSL_DIR=$HOME/wolfssl-install
-        # Deviations (documented at
-        # https://github.com/wolfSSL/wolfCOSE/wiki/MISRA-Compliance):
+        # Deviations (documented in docs/MISRA-Compliance.md):
         #
         # -bugprone-branch-clone: Different COSE algorithms intentionally
         #   map to the same wolfCrypt value (e.g. ES512 and EdDSA both

.github/workflows/publish-docs-image.yml

@@ -0,0 +1,42 @@
+name: Publish documentation image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docker/docs/**'
+      - '.github/workflows/publish-docs-image.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: publish-wolfcose-docs-image
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.repository == 'wolfSSL/wolfCOSE'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Select image tag
+        id: image
+        run: |
+          image_sha=$(sha256sum docker/docs/Dockerfile docker/docs/requirements.txt | sha256sum | cut -c1-16)
+          echo "tag=ghcr.io/wolfssl/wolfcose-docs:sha-$image_sha" >> "$GITHUB_OUTPUT"
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: docker/docs
+          file: docker/docs/Dockerfile
+          push: true
+          tags: ${{ steps.image.outputs.tag }}

.gitignore

@@ -8,6 +8,9 @@ experimental-check.err
 *.dSYM/
 .wolfcose-build-config
 
+# Docs manual build output (see DOCS-BUILD.md)
+/build/
+
 # Binaries
 tests/test_wolfcose
 tests/test_wolfcose_eat_psa

ChangeLog.md

@@ -187,7 +187,7 @@ MAC, and key distribution, and standardized post-quantum ML-DSA signatures
 
 * Minimal footprint: an ES256 `COSE_Sign1` build is ~5.1 KB verify-only and
   ~6.8 KB sign + verify for the wolfCOSE COSE + CBOR engine; see the
-  [Footprint](https://github.com/wolfSSL/wolfCOSE/wiki/Footprint) page for
+  [Footprint](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html) page for
   total-flash numbers including wolfCrypt.
 * MISRA C:2012 and C:2023 checked.
 * API hardening: `COSE_Encrypt` and `wc_CoseMac_Create` direct mode now require

IDE/STM32Cube/README.md

@@ -41,5 +41,5 @@ wolfCOSE is configured through the wolfSSL `user_settings.h` (included before
 wolfCrypt features (`HAVE_ECC`, `WOLFSSL_SHA384/512`, `WOLFSSL_HAVE_MLDSA`).
 
 See the wolfCOSE `examples/` for sign1, mac0, and encrypt0 usage, and the
-[STM32Cube wiki page](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube) for
+[STM32Cube manual page](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html) for
 the full walkthrough including a ready to run NUCLEO-H563ZI project.

README.md

@@ -23,12 +23,12 @@ wolfCOSE is a lightweight and fast C library implementing core CBOR and COSE sta
 * **Post-Quantum Cryptography:**
   * ML-DSA (FIPS 204 / RFC 9964) at all security levels.
   * HSS/LMS stateful hash-based signing (RFC 8778 / CNSA 2.0).
-* **Fast Performance:** On an Intel i9-11950H, end-to-end `COSE_Sign1` reaches 66,538 sign/s and 26,437 verify/s with ES256, and 21,986 sign/s and 53,686 verify/s with ML-DSA-44. See the [performance and footprint details](https://github.com/wolfSSL/wolfCOSE/wiki/Footprint) and [wolfCOSE vs. The Field](https://www.wolfssl.com/wolfcose-vs-the-field-the-smallest-and-fastest-cose-library-now-with-post-quantum-ml-dsa-at-the-same-cost/).
+* **Fast Performance:** On an Intel i9-11950H, end-to-end `COSE_Sign1` reaches 66,538 sign/s and 26,437 verify/s with ES256, and 21,986 sign/s and 53,686 verify/s with ML-DSA-44. See the [performance and footprint details](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html) and [wolfCOSE vs. The Field](https://www.wolfssl.com/wolfcose-vs-the-field-the-smallest-and-fastest-cose-library-now-with-post-quantum-ml-dsa-at-the-same-cost/).
 * **PSA Attestation:** EAT / PSA Token issuance and verification with delegated HSM signing support.
 * **41 Cryptographic Algorithms:** Broad algorithm coverage across signing, encryption, MAC, and key distribution.
 * **Embedded-First Design:** Zero dynamic memory allocation (no heap, zero `.data`/`.bss`). Operates on caller-supplied buffers with bounded stack usage.
 * **FIPS 140-3 Path:** Uses wolfCrypt (FIPS Certificate #4718) as its sole cryptographic dependency.
-* **STM32 Integrated:** Drop-in STM32Cube pack (`I-CUBE-wolfCOSE`) available for STM32CubeMX / IDE ([Details](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube)).
+* **STM32 Integrated:** Drop-in STM32Cube pack (`I-CUBE-wolfCOSE`) available for STM32CubeMX / IDE ([Details](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html)).
 
 ## Supported Algorithms
 
@@ -71,7 +71,7 @@ the corresponding `wc_Cose_VerifyCounterSignature*()` API.
 
 wolfCOSE requires [wolfSSL](https://www.wolfssl.com/) as its crypto backend.
 **Minimum supported version: v5.8.0-stable**. Some optional algorithms require
-newer releases; see [Getting Started](docs/Getting-Started.md#prerequisites) for
+newer releases; see [Getting Started](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html#prerequisites) for
 feature-specific dependency floors and build instructions. HSS/LMS (RFC 8778)
 requires v5.9.2-stable or later.
 
@@ -104,7 +104,7 @@ stack and disable the algorithms a Sign1 + Encrypt0 build never uses:
             --disable-errorstrings
 ```
 
-See [Tuning for Size](docs/Macros.md#tuning-for-size) and [Tuning for Speed](docs/Macros.md#tuning-for-speed)
+See [Tuning for Size](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-size) and [Tuning for Speed](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-speed)
 for squeezing wolfCOSE and wolfCrypt further on MCUs.
 
 ### Minimal Build (Post-Quantum / ML-DSA only)
@@ -213,19 +213,25 @@ make coverage-force-failure    # Include crypto failure path testing
 
 ## Documentation
 
-Full documentation is available in the [Wiki](https://github.com/wolfSSL/wolfCOSE/wiki):
-
-- [Getting Started](https://github.com/wolfSSL/wolfCOSE/wiki/Getting-Started): Build instructions and first steps
-- [Message Types](https://github.com/wolfSSL/wolfCOSE/wiki/Message-Types): All six RFC 9052 messages (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) and RFC 9338 countersignatures with code samples
-- [Algorithms](https://github.com/wolfSSL/wolfCOSE/wiki/Algorithms): Complete list of 41 supported algorithms with COSE IDs
-- [API Reference](https://github.com/wolfSSL/wolfCOSE/wiki/API-Reference): Function signatures, data structures, error codes
-- [Macros](https://github.com/wolfSSL/wolfCOSE/wiki/Macros): Compile-time configuration, size tuning, and ECDSA nonce policy
-- [PSA-EAT](https://github.com/wolfSSL/wolfCOSE/wiki/PSA-EAT): RFC 9783 PSA token profiles, APIs, macros, and security guidance
-- [Footprint](https://github.com/wolfSSL/wolfCOSE/wiki/Footprint): Size and speed numbers, desktop and on-device
-- [Testing](https://github.com/wolfSSL/wolfCOSE/wiki/Testing): Test infrastructure, coverage, and failure injection
-- [MISRA Compliance](https://github.com/wolfSSL/wolfCOSE/wiki/MISRA-Compliance): MISRA C:2012 and C:2023 compliance status and deviation rationale
-- [Project Structure](https://github.com/wolfSSL/wolfCOSE/wiki/Project-Structure): Source file layout
-- [STM32Cube](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube): Install and run wolfCOSE as an STM32Cube pack on device
+The official wolfCOSE manual is published at
+[wolfssl.com/documentation/manuals/wolfcose](https://www.wolfssl.com/documentation/manuals/wolfcose/index.html):
+
+- [Getting Started](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html): Build instructions and first steps
+- [Message Types](https://www.wolfssl.com/documentation/manuals/wolfcose/Message-Types.html): All six RFC 9052 messages (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) and RFC 9338 countersignatures with code samples
+- [Algorithms](https://www.wolfssl.com/documentation/manuals/wolfcose/Algorithms.html): Complete list of 41 supported algorithms with COSE IDs
+- [API Reference](https://www.wolfssl.com/documentation/manuals/wolfcose/API-Reference.html): Function signatures, data structures, error codes
+- [Macros](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html): Compile-time configuration, size tuning, and ECDSA nonce policy
+- [PSA-EAT](https://www.wolfssl.com/documentation/manuals/wolfcose/PSA-EAT.html): RFC 9783 PSA token profiles, APIs, macros, and security guidance
+- [Footprint](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html): Size and speed numbers, desktop and on-device
+- [Testing](https://www.wolfssl.com/documentation/manuals/wolfcose/Testing.html): Test infrastructure, coverage, and failure injection
+- [MISRA Compliance](https://www.wolfssl.com/documentation/manuals/wolfcose/MISRA-Compliance.html): MISRA C:2012 and C:2023 compliance status and deviation rationale
+- [Project Structure](https://www.wolfssl.com/documentation/manuals/wolfcose/Project-Structure.html): Source file layout
+- [STM32Cube](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html): Install and run wolfCOSE as an STM32Cube pack on device
+
+The manual sources live in [`docs/`](docs/); `mkdocs.yml` defines the navigation
+and the shared [`wolfSSL/documentation`](https://github.com/wolfSSL/documentation)
+tooling builds the HTML and PDF. See [docs/dev/DOCS-BUILD.md](docs/dev/DOCS-BUILD.md)
+for local previews and how changes reach the website.
 
 ## Release Notes
 

docker/docs/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim-bookworm
+
+LABEL org.opencontainers.image.source="https://github.com/wolfSSL/wolfCOSE"
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        bash git make patch perl librsvg2-bin \
+        pandoc texlive-xetex texlive-latex-extra texlive-fonts-recommended \
+        fonts-noto-core fonts-noto-mono lmodern \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /tmp/requirements-docs.txt
+RUN python -m pip install --no-cache-dir -r /tmp/requirements-docs.txt
+
+WORKDIR /work

docker/docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs==1.6.1

docs/API-Reference.md

@@ -1164,7 +1164,7 @@ pin the same algorithm.
 ## PSA/EAT API
 
 Available only when `WOLFCOSE_ENABLE_EAT_PSA` and the selected profile and
-envelope gates are defined. Include `<wolfcose/eat_psa.h>`. See [[PSA-EAT]]
+envelope gates are defined. Include `<wolfcose/eat_psa.h>`. See [PSA-EAT](PSA-EAT.md)
 for configuration and security requirements.
 
 ### wc_CoseEatPsaToken_Verify
@@ -1415,7 +1415,7 @@ numeric `crit` is rejected. `wc_CoseKey_Decode()` and
 
 ## See Also
 
-- [[Getting Started]]: Build instructions and examples
-- [[Algorithms]]: Supported algorithms
-- [[Macros]]: Compile-time configuration
-- [[PSA-EAT]]: RFC 9783 PSA attestation support
+- [Getting Started](Getting-Started.md): Build instructions and examples
+- [Algorithms](Algorithms.md): Supported algorithms
+- [Macros](Macros.md): Compile-time configuration
+- [PSA-EAT](PSA-EAT.md): RFC 9783 PSA attestation support

docs/Algorithms.md

@@ -1,6 +1,6 @@
 # Supported Algorithms
 
-wolfCOSE supports 46 algorithms across signing, encryption, MAC, and key distribution. This page provides the complete list with COSE algorithm IDs and required wolfSSL compile-time guards. All algorithms are usable in both single-actor messages (Sign1/Encrypt0/Mac0) and multi-actor messages (Sign/Encrypt/Mac). See [[Message Types]] for details.
+wolfCOSE supports 46 algorithms across signing, encryption, MAC, and key distribution. This page provides the complete list with COSE algorithm IDs and required wolfSSL compile-time guards. All algorithms are usable in both single-actor messages (Sign1/Encrypt0/Mac0) and multi-actor messages (Sign/Encrypt/Mac). See [Message Types](Message-Types.md) for details.
 
 ## COSE_Sign1 (Digital Signatures)
 
@@ -224,6 +224,6 @@ Future algorithm support planned:
 
 ## See Also
 
-- [[Getting Started]]: Build instructions and examples
-- [[API Reference]]: Function documentation
-- [[Macros]]: Compile-time configuration
+- [Getting Started](Getting-Started.md): Build instructions and examples
+- [API Reference](API-Reference.md): Function documentation
+- [Macros](Macros.md): Compile-time configuration

docs/Footprint.md

@@ -28,7 +28,7 @@ The verify-only profile is the common on-device case: a device verifies signed f
 
 ## Build-profile footprint
 
-The lean profiles (see [[Macros]] → Build Profiles). *Glue* is the wolfCOSE engine alone; *total* adds the minimal wolfCrypt backend.
+The lean profiles (see [Macros](Macros.md) -> Build Profiles). *Glue* is the wolfCOSE engine alone; *total* adds the minimal wolfCrypt backend.
 
 | Profile | Algorithm | wolfCOSE glue | Total + wolfCrypt |
 |---------|-----------|---------------|-------------------|
@@ -78,6 +78,6 @@ Desktop: x86_64 Intel i9-11950H, GCC 14.2. ES256 was measured in June 2026 using
 
 ## See Also
 
-- [[Macros]]: build profiles and configuration
-- [[Testing]]: memory and stack-bound enforcement in CI
-- [[Getting Started]]: building wolfCOSE
+- [Macros](Macros.md): build profiles and configuration
+- [Testing](Testing.md): memory and stack-bound enforcement in CI
+- [Getting Started](Getting-Started.md): building wolfCOSE

docs/Getting-Started.md

@@ -482,7 +482,7 @@ Related strictness that surprises integrators for the same reason:
 
 - Trailing bytes after the encoded object are rejected. `inSz` must be exactly
   the object length, not the capacity of the buffer holding it. Use
-  [`wc_CBOR_SkipItem()`](API-Reference.md#wc_cbor_skipitem) to carve out the
+  [`wc_CBOR_SkipItem()`](API-Reference.md#decoding-functions) to carve out the
   exact byte range of an embedded item.
 - Two-byte simple values below 32 are malformed, per RFC 8949.
 - All encountered CBOR text strings are validated as UTF-8. This also applies
@@ -534,7 +534,7 @@ Per-function stack usage (from `-fstack-usage`, GCC, `-Os`, aarch64):
 
 ## Next Steps
 
-- [[Algorithms]]: See all supported algorithms
-- [[API Reference]]: Complete function documentation
-- [[Macros]]: Configure compile-time options
-- [[Testing]]: Run tests and measure coverage
+- [Algorithms](Algorithms.md): See all supported algorithms
+- [API Reference](API-Reference.md): Complete function documentation
+- [Macros](Macros.md): Configure compile-time options
+- [Testing](Testing.md): Run tests and measure coverage