PRJ: Domus PDF Export

Project Summary

Field Value

PRJ ID

PRJ-domus-pdf-export

Owner

Evan Rosado

Priority

P2

Category

Documentation / Tooling

Status

Active

Location

domus-docs/scripts/antora-to-pdf.py

Language

Python

Dependencies

WeasyPrint, Antora

Created

2026-04-01

Overview

Converts Antora HTML pages to styled PDF documents using WeasyPrint. Strips the dark theme CSS, injects a print stylesheet, builds a table of contents from headings, and replaces Font Awesome admonition icons with text labels. Produces clean, branded PDFs suitable for client deliverables.

Problem

  • Antora builds beautiful HTML sites but has no native PDF export

  • asciidoctor-pdf uses its own theme engine — output looks nothing like the Antora site

  • The domus dark theme (domus-theme.css) uses !important everywhere, making CSS overrides unreliable

  • Font Awesome icons don’t render in non-browser PDF engines

  • Antora’s TOC is JavaScript-populated — empty in static HTML

Solution

Python script (antora-to-pdf.py) that:

  1. Builds the Antora site via the playbook

  2. Reads the generated HTML

  3. Strips site.css (removes dark theme entirely)

  4. Injects data-theme="light" (prevents FOUC visibility hide)

  5. Builds TOC from h2/h3 headings

  6. Replaces Font Awesome admonition icons with styled text labels (NOTE, WARNING, TIP, etc.)

  7. Applies a clean print stylesheet via WeasyPrint

  8. Outputs Letter-sized PDF with page numbers

Architecture

antora-playbook.yml
    ↓ npx antora
build/site/**/*.html
    ↓ antora-to-pdf.py
    ├── Strip site.css (dark theme)
    ├── Inject data-theme="light"
    ├── Build TOC from headings
    ├── Replace FA icons → text labels
    └── Apply PRINT_CSS
build/export/*.pdf

Location

  • domus-docs/scripts/antora-to-pdf.py — hub repo, works against full aggregated site

  • domus-docs/Makefile — make styled-pdf target for any component page

Usage

# From any spoke repo (current)
make styled-pdf PAGE=case-studies/tac/TAC-2026-04-gcc-ise-cert-import.html

# From domus-docs hub (target)
make styled-pdf PAGE=captures/case-studies/tac/TAC-2026-04-gcc-ise-cert-import.html
make styled-pdf PAGE=ise-linux/02-pki/certificate-enrollment.html
make styled-pdf PAGE=infra-ops/runbooks/vyos-deployment.html

Dependencies

  • Python 3

  • WeasyPrint (pip install weasyprint)

  • Antora (for building the HTML site)

Remaining Work

  • Move script to domus-docs

  • Add styled-pdf Makefile target to domus-docs

  • Remove prototype from domus-captures

  • Test against other spoke repos (ise-linux, infra-ops, secrets-ops)

  • Add cover page option with project branding

  • Add --all flag to batch-export entire directories

  • Consider dark-mode PDF variant (white text on dark background)

Origin

Built during the GCC ISE certificate import engagement (TAC-2026-04-gcc-ise-cert-import) when the need arose to produce a professional PDF deliverable from Antora documentation.

Metadata

Field Value

PRJ ID

PRJ-domus-pdf-export

Author

Evan Rosado

Date Created

2026-04-01

Last Updated

2026-04-03

Status

Active

Related