Integrate publication pipeline and design updates

.github/workflows/documents.yml

@@ -0,0 +1,63 @@
+name: Verify PDF publications
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/documents.yml'
+      - 'source/chapters/**'
+      - 'source/pdf/**'
+      - 'docs/pdf/**'
+  push:
+    branches:
+      - main
+    paths:
+      - '.github/workflows/documents.yml'
+      - 'source/chapters/**'
+      - 'source/pdf/**'
+      - 'docs/pdf/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install document utilities and fonts
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes fonts-noto-mono fonts-texgyre poppler-utils
+
+      - name: Install Pandoc 3.9.0.2
+        run: |
+          curl --fail --location --silent --show-error \
+            --output /tmp/pandoc.deb \
+            https://github.com/jgm/pandoc/releases/download/3.9.0.2/pandoc-3.9.0.2-1-amd64.deb
+          echo 'ce4ac48f48aa7eadc1f5dbdf3449a1739f188ecb8c5421c5adc070fe7479e567  /tmp/pandoc.deb' \
+            | sha256sum --check
+          sudo dpkg --install /tmp/pandoc.deb
+
+      - uses: typst-community/setup-typst@v5
+        with:
+          typst-version: 0.14.2
+
+      - name: Install Mermaid CLI 11.16.0
+        run: npm install --global @mermaid-js/mermaid-cli@11.16.0
+
+      - name: Test Typst post-processing
+        run: python3 -m unittest discover -s source/pdf/tests -p 'test_*.py'
+
+      - name: Rebuild and verify published PDFs
+        run: ./source/pdf/build-all.sh --check
+
+      - name: Upload rebuilt PDFs on failure
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: rebuilt-pdfs
+          path: source/pdf/*.pdf
+          if-no-files-found: error
+          retention-days: 7

.gitignore

@@ -20,8 +20,12 @@ source/pdf/*
 !source/pdf/metadata-suite-map.yaml
 !source/pdf/build-lite.sh
 !source/pdf/build-common.sh
+!source/pdf/build-all.sh
+!source/pdf/README.md
 !source/pdf/pandoc-typst-lite.typ
 !source/pdf/.gitignore
+!source/pdf/tests/
+!source/pdf/tests/test_postprocess_typst.py
 .venv/
 site/
 __pycache__/

README.md

@@ -32,6 +32,16 @@ pip install mkdocs mkdocs-material
 mkdocs serve        # http://127.0.0.1:8000
 ```
 
+To rebuild and verify the public PDF suite (Pandoc 3.2+, Typst 0.14+, Mermaid
+CLI 11+, and Poppler required):
+
+```bash
+./source/pdf/build-all.sh --publish
+```
+
+See [the PDF pipeline guide](source/pdf/README.md) for profiles, accessibility
+requirements, and reproducibility checks.
+
 ## Licence
 
 See [About This Project](https://semanticdefects.foundryside.dev/reference/about/) for attribution and licence details.