input-output-hk · ch1bo · Oct 29, 2025 · Oct 25, 2025
diff --git a/.github/workflows/leios-design.yaml b/.github/workflows/leios-design.yaml
@@ -0,0 +1,99 @@
+name: "Build Leios Design PDF"
+
+on:
+  pull_request:
+    paths:
+      - "docs/leios-design/**"
+      - "nix/artifacts.nix"
+      - ".github/workflows/leios-design.yaml"
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/leios-design/**"
+      - "nix/artifacts.nix"
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: read
+  actions: read
+
+# Prevent redundant workflow runs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-pdf:
+    name: "Build Leios Design PDF"
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: 🛠️ Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+            extra-substituters = https://cache.iog.io
+            extra-trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=
+
+      - name: 🗂️ Setup Cachix for IOG cache
+        uses: cachix/cachix-action@v15
+        with:
+          name: iog
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          skipPush: true
+
+      - name: 🏗️ Build PDF using Nix
+        run: |
+          echo "Building Leios Design PDF..."
+          nix build .#leiosDesignPdf -L
+
+          # Verify the PDF was created
+          if [ ! -f result/leios-design.pdf ]; then
+            echo "Error: PDF file was not created"
+            exit 1
+          fi
+
+          # Show file size and info
+          ls -lh result/leios-design.pdf
+          file result/leios-design.pdf
+
+      - name: 📊 Get PDF metadata
+        run: |
+          # Get basic file info
+          echo "PDF file size: $(stat -c%s result/leios-design.pdf) bytes"
+          echo "PDF creation date: $(stat -c%y result/leios-design.pdf)"
+
+          # If pdfinfo is available, show more details
+          if command -v pdfinfo &> /dev/null; then
+            echo "PDF metadata:"
+            pdfinfo result/leios-design.pdf || true
+          fi
+
+      - name: 🚀 Upload PDF artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: leios-design-pdf-${{ github.sha }}
+          path: result/leios-design.pdf
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: 📄 Add PDF info to job summary
+        run: |
+          echo "## 📄 Leios Design PDF Generated" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "✅ Successfully built PDF from markdown source" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**File details:**" >> $GITHUB_STEP_SUMMARY
+          echo "- Size: $(stat -c%s result/leios-design.pdf) bytes" >> $GITHUB_STEP_SUMMARY
+          echo "- Generated: $(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY
+          echo "- Commit: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "The PDF is available as a workflow artifact named \`leios-design-pdf-${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
diff --git a/docs/leios-design/README.md b/docs/leios-design/README.md
@@ -1,8 +1,8 @@
 ---
-Title: Leios technical design and implementation plan
-Status: Draft
-Version: 0.2
-Authors:
+title: Leios technical design and implementation plan
+status: Draft
+version: 0.2
+author:
   - Sebastian Nagel <[email protected]>
 ---
 
@@ -709,7 +709,7 @@ The testnet enables multiple validation categories. Functional testing verifies
 
 The testnet integrates ecosystem tooling: wallets handling increased throughput, block explorers understanding new structures, monitoring systems tracking Leios metrics, and stake pool operator documentation and deployment guides. Crucially, the testnet further enables empirical parameter selection (size limits, timing parameters), where simulation provides initial guidance but real-world testing with community feedback informs acceptable mainnet values.
 
-Software deployed to the public testnet progressively converges toward mainnet release candidates. Early deployments may use instrumented prototypes lacking production optimizations; later upgrades run increasingly complete and optimized implementations. Eventually, all changes as [outlined in this design document](#Architecture) must be realized in the `cardano-node` and other node implementations. This progressive refinement maintains community engagement while preserving engineering velocity. Traces from testnet nodes can still be verified against formal specifications using the trace verification approach, ultimately linking the abstraction layers.
+Software deployed to the public testnet progressively converges toward mainnet release candidates. Early deployments may use instrumented prototypes lacking production optimizations; later upgrades run increasingly complete and optimized implementations. Eventually, all changes as [outlined in this design document](#architecture) must be realized in the `cardano-node` and other node implementations. This progressive refinement maintains community engagement while preserving engineering velocity. Traces from testnet nodes can still be verified against formal specifications using the trace verification approach, ultimately linking the abstraction layers.
 
 ## Mainnet deployment readiness
 
@@ -741,6 +741,9 @@ Operational readiness encompasses stake pool operator testing in their environme
 
 # References
 
+> [!WARNING]
+> TODO: Use pandoc-compatible citations https://pandoc.org/MANUAL.html#citation-syntax
+
 1. **CIP-164**: Ouroboros Linear Leios - Greater transaction throughput https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md
 
 1. **Leios Impact Analysis**: High-level component design https://github.com/input-output-hk/ouroboros-leios/blob/main/docs/ImpactAnalysis.md

diff --git a/docs/leios-design/metadata.yaml b/docs/leios-design/metadata.yaml
@@ -0,0 +1,21 @@
+# Pandoc PDF metadata
+toc: true
+numbersections: true
+highlight-style: haddock
+documentclass: scrartcl
+fontsize: 11pt
+geometry:
+  - margin=2.5cm
+  - top=3cm
+  - bottom=3cm
+colorlinks: true
+linkcolor: NavyBlue
+urlcolor: NavyBlue
+citecolor: NavyBlue
+toccolor: black
+papersize: a4
+linestretch: 1.15
+indent: false
+header-includes: |
+  \usepackage{microtype}
+  \usepackage[T1]{fontenc}
diff --git a/nix/artifacts.nix b/nix/artifacts.nix
@@ -33,7 +33,30 @@ let
     '';
   };
 
+  leiosDesignPdf = pkgs.stdenv.mkDerivation {
+    name = "leios-design-pdf";
+    src = ../docs/leios-design;
+    buildInputs = [
+      pkgs.pandoc
+      pkgs.texliveFull
+      pkgs.librsvg
+    ];
+    buildPhase = ''
+      # Work directly in the source directory where all assets are available
+      cd $src
+      mkdir -p $out
+
+      # Convert markdown to PDF using pandoc with XeLaTeX
+      pandoc README.md \
+        --pdf-engine=xelatex \
+        --from=markdown \
+        --to=pdf \
+        --metadata-file metadata.yaml \
+        --output=$out/leios-design.pdf
+    '';
+  };
+
 in
 {
-  inherit simRealism networkSpec;
+  inherit simRealism networkSpec leiosDesignPdf;
 }