17 The Publishing Pipeline

Scope: Manuscript-to-deployment pipeline — HTML, PDF, EPUB output + CI/CD
Duration: Multiple waves within a single extended session
Theme: Infrastructure automation and the “Almost Done” cascade

From manuscript to multi-format deployment: the Agentic SDLC applied to publishing infrastructure

Key Takeaways — The TL;DR

Every design decision was human; every technical execution was agent — that division held throughout.
The “Almost Done” Trap is real: each PDF fix exposed the next issue, five layers deep. Treat each fix as its own micro-wave with a checkpoint.
CI and local rendering serve different masters — optimize CI for speed (HTML-only, 49s), local for completeness (all formats).
Expert panels produce better outcomes than solo research, but the human still chooses the publishing philosophy.

17.1 The Problem

You have a 15-chapter technical handbook in Markdown. You want readers to find it as a fast-loading website, a downloadable PDF, and an EPUB for e-readers — all auto-deployed from a single source. The publishing industry offers dozens of toolchains, each with trade-offs in cost, control, update friction, and reader reach.

The author knew what the book should feel like. The agents knew how to make it work.

17.2 Publishing Strategy: Three Rounds of Deliberation

The first wave wasn’t code — it was research. The orchestrator’s initial recommendation was an Open Core model: free web, paid PDF/EPUB. The author pushed back immediately: “Why not Amazon ebooks? Why just PDF in a repo?”

A research agent investigated Quarto, Leanpub, GitBook, and mdBook. The revised recommendation — Leanpub plus Amazon KDP plus a GitHub source repo — was closer, but the author pushed again: What’s state of the art for free tech books with regular updates?

The final answer was Quarto + GitHub Pages, the pattern used by R for Data Science and Python for Data Analysis. One source repository. Markdown-native authoring. Multi-format output. CI/CD deployment. Zero hosting cost.

This three-round deliberation illustrates a property tested under real conditions: human judgment remains the bottleneck and differentiator. The agents surfaced options and trade-offs; the human chose the publishing philosophy.

17.3 The Conversion Wave

A single general-purpose agent converted the entire manuscript in one wave:

Created _quarto.yml with a four-part book structure (Foundation, Leaders, Practitioners, Closing)
Converted 15 .md files to .qmd via git mv — preserving git history at 99% similarity
Added YAML frontmatter to each chapter
Created index.qmd with a reading guide and download callouts
Created .github/workflows/publish.yml for CI auto-deploy

HTML render: 16 files, zero errors, 25 Mermaid diagrams confirmed. The site went live on the gh-pages branch within the same wave.

flowchart LR
    A["15 Markdown<br/>chapters"] --> B["git mv .md → .qmd<br/>+ YAML frontmatter"]
    B --> C["_quarto.yml<br/>book config"]
    C --> D["quarto render"]
    D --> E["HTML<br/>(web)"]
    D --> F["PDF<br/>(LaTeX)"]
    D --> G["EPUB"]
    E --> H["GitHub Pages<br/>CI deploy"]
    F --> I["Local render<br/>+ copy to site"]
    G --> I

Figure 17.1: Publishing conversion pipeline: Markdown to HTML, PDF, and EPUB

17.4 The “Almost Done” Trap: PDF Rendering Cascade

What happened next is a textbook instance of Anti-Pattern #15: The “Almost Done” Trap — each fix revealed the next issue, creating a cascade where “one more fix” repeated five times.

flowchart TD
    A["PDF renders ✓<br/>text too narrow"] -->|scrreprt class| B["Layout fixed ✓<br/>Mermaid missing"]
    B -->|syntax fix| C["Diagrams render ✓<br/>duplicate numbers"]
    C -->|strip numbers| D["Headings clean ✓<br/>margins overflow"]
    D -->|fig-width+wrap| E["Overflow fixed ✓<br/>fig-width too wide"]
    E -->|5.5 + preamble| F["PDF clean ✓<br/>686KB → 3.8MB"]

Figure 17.2: The ‘Almost Done’ trap: cascading PDF rendering fixes

Issue 1 — Narrow text. The scrbook document class has wide binding margins designed for physical books. Fix: switch to scrreprt with explicit geometry (25mm left/right, 30mm top/bottom).

Issue 2 — Missing Mermaid diagrams. All 15 chapters used GitHub-flavored ```mermaid fences. Quarto requires ```{mermaid} for PDF rendering via headless Chromium. This was Anti-Pattern #10: Not Fixing the Primitives — the syntax was wrong at the source level across every chapter. A bulk sed conversion fixed all 24 blocks; the PDF grew from 686KB to 3.8MB as rendered diagram PNGs appeared.

Issue 3 — Duplicate heading numbers. Manual numbers in headings (### 1. The Monolithic Prompt) clashed with Quarto’s auto-numbering, producing 15.2.1 1. in the PDF. Stripped manual numbers from 25 headings across two chapters.

Issue 4 — Margin overflow. Diagrams and code blocks exceeded the text area. Added fig-width: 6.5, code-overflow: wrap, and LaTeX packages (fvextra, float). Then discovered 6.5 inches exceeded the 6.3-inch usable width — reduced to 5.5 and created preamble.tex with \small font for long table environments.

Issue 5 — ASCII art table. Chapter 4 contained a complex ASCII art SDLC phases table that rendered as a code block in PDF. Converted to a proper 9-column markdown pipe table.

Each fix was technically correct. The trap is that correctness at one layer exposes incorrectness at the next. The orchestrator treated each as a new micro-wave with its own checkpoint – never batching speculative fixes.

Try This: Micro-Wave Checkpoints for Cascade Fixes

When each fix reveals the next issue (the “Almost Done” cascade), treat each fix as its own wave:

Make one fix
Render/build to see the result
Commit before touching anything else
Only then investigate the next issue

This prevents speculative batching – fixing three things at once when you don’t yet know if fix #1 changes the landscape for fixes #2 and #3.

17.5 CI/CD: Four Iterations to Stability

The deployment pipeline went through its own iteration gauntlet:

Iteration	Failure	Fix
1	Mermaid→PNG via headless Chromium hung on CI	Added `quarto install chromium --no-prompt`
2	Custom LaTeX packages (DejaVu fonts, fvextra) hung CI	Simplified PDF config, removed custom fonts
3	`render: "html"` param to publish action — `_book` dir not found	Split into explicit `quarto render --to html` then `quarto publish` with `render: false`
4	CI HTML-only deploy overwrote PDF/EPUB on `gh-pages`	Added “Restore PDF and EPUB from gh-pages” step using `git show`

The final architecture splits rendering by environment:

flowchart TB
    subgraph CI ["CI Pipeline (49s)"]
        A1["Checkout"] --> A2["Install Quarto"]
        A2 --> A3["render --to html"]
        A3 --> A4["Restore PDF/EPUB<br/>from gh-pages"]
        A4 --> A5["publish --no-render"]
    end

    subgraph Local ["Local Render (15 min)"]
        B1["render --to pdf"] --> B2["Save PDF"]
        B2 --> B3["render --to epub"]
        B3 --> B4["Save EPUB"]
        B4 --> B5["render --to html"]
        B5 --> B6["Copy PDF + EPUB<br/>into _book/"]
        B6 --> B7["publish --no-render"]
    end

Figure 17.3: Final CI/CD architecture: CI pipeline and local render workflow

The 15-minute local render is a practical constraint – Chromium-based Mermaid rendering is too heavy for a fast CI feedback loop. The architecture makes this explicit: CI optimizes for speed (HTML-only, 49 seconds), local optimizes for completeness (all formats).

17.7 Licensing: Expert Panel Deliberation

A three-expert panel (IP Attorney, Publishing Strategist, Growth Hacker) evaluated licensing options. The recommendation was unanimous: CC BY-NC-ND 4.0.

The rationale maps to four properties: invites sharing (reach), requires attribution (authorship), prohibits commercial use (author’s brand), prohibits derivatives (one canonical version). Implementation touched four files – LICENSE, README.md, index.qmd, and the _quarto.yml footer.

17.8 What This Case Study Shows

The publishing pipeline compressed weeks of toolchain research, format debugging, and CI configuration into focused waves of agent execution guided by human judgment.

What Held True. The structural properties from the APM Overhaul held. The novel test: the “Almost Done” cascade demonstrated that checkpoint discipline prevents compounding rendering failures as effectively as it prevents compounding code failures.

Metrics

3 output formats (HTML, PDF, EPUB) · 37 Mermaid diagrams rendered · 5 PDF/EPUB rendering fixes (cascade) · 4 CI/CD iterations · 7 download UX iterations · 3 expert panel deliberations · 49-second CI deploy

The division of labor was consistent: every design decision was human; every technical execution was agent.

This case study documents the publishing pipeline for The Agentic SDLC Handbook. The book, the pipeline, and this case study were all produced using the methodology described in Chapters 12–15.