← All projects
active

Quarto Book Template

Open-source template for writing technical books with executable code, tested snippets against live Postgres, Mermaid diagrams, pre-commit hooks, supply chain security, and GitHub Actions CI.

Open SourcePythonAutomationInfrastructure
GitHub →

The Problem

Technical books rot. You publish with pandas==2.1, a year later readers install pandas==3.0, and half the examples break. The traditional approach — maintaining a separate test repo alongside the manuscript — creates drift between what’s tested and what’s printed.

Approach

A Quarto book template where code examples execute against real infrastructure during render:

  • Executable code blocks — Python code runs against a live Postgres database (Docker Compose), output captured directly in the book
  • Snippet extraction — infrastructure-heavy code extracted from a tested repository with a CI linter that catches broken references
  • Mermaid diagrams — rendered inline, PDF-friendly with width constraints
  • Pre-commit hooks — ruff, gitleaks, snippet linting on every commit
  • Supply chain security — 7-day Renovate delay, Docker images pinned by SHA256 digest, locked dependencies
  • Split CI — lint and test on every push (cheap), full render only on manual dispatch (saves compute)

If psycopg2 or pandas release a breaking change, the build fails before readers encounter it.