Skip to content

Publication Pipeline 101

FCC publishes a single source set to five formats: HTML (web), PDF (print), EPUB (ebook), DOCX (editorial), PPTX/reveal.js (slides). The pipeline runs via make pub-all and produces 27 artifacts from one publications/ directory. This page explains how and what to adopt at your own scale.

The pipeline at a glance

Markdown sources (docs/)
        |
        v
  Jinja templates (src/fcc/templates/docs/) ---+
        |                                      |
        v                                      v
Generated Markdown (docs/model-cards/, etc)   Narrative Markdown (docs/guidebook/)
        |                                      |
        +------------ ^ ---------- +
                      |
                      v
              Pandoc + Quarto
                      |
         +------+-----+-----+-----+----+
         |      |     |     |     |    |
        HTML   PDF  EPUB  DOCX  PPTX  reveal.js

You start with Markdown + templates; you end with publishable artifacts in six formats. A single command orchestrates everything.

What each tool does

  • Pandoc. Accepts Markdown; emits PDF (via LaTeX or Typst), EPUB, DOCX, etc.
  • Quarto. Accepts Markdown with front matter; coordinates Pandoc, code execution, figure rendering. Supports project-level config.
  • Typst. PDF typesetting; modern replacement for LaTeX. Faster, friendlier errors, easier templates.
  • MkDocs-material. HTML-only; what powers the web docs.

FCC uses all four. A simpler project might use only MkDocs (web) + Pandoc (one PDF).

Quarto project layout

publications/
├── _quarto.yml              # project config, book layout
├── _quarto-executive.yml    # executive-edition overlay
├── _quarto-academic.yml     # academic overlay
├── presentations/           # PPTX + reveal.js
├── reference-cards/         # five 1-page PDFs (.qmd source)
├── templates/               # Word/PowerPoint templates
├── scripts/
│   └── build_all.sh         # driver script
└── _output/                 # rendered artifacts (committed)

The three _quarto-*.yml files let one source tree produce three audiences (full book, executive summary, academic paper) without duplication.

A minimal _quarto.yml

project:
  type: book
  output-dir: _output/books

book:
  title: "Our Handbook"
  author: "Team Handbook"
  chapters:
    - index.md
    - introduction.md
    - chapter-1.md
    - chapter-2.md
    - references.md

format:
  html: default
  pdf:
    engine: typst
  epub: default
  docx: default

Four output formats from one config. Run quarto render.

Cascading profiles

The executive overlay subsets the chapter list:

book:
  chapters:
    - index.md
    - executive-summary.md
    - key-recommendations.md
    - references.md

Run: quarto render --profile executive. Output lands in _output/executive/.

A single handbook becomes a full book and a 20-page executive edition from the same Markdown. No copy-paste.

Mermaid + PDF

Pandoc PDF rendering (via Typst or LaTeX) does not natively support Mermaid. FCC's solution: a Pandoc Lua filter (render_mermaid.py-driven wrapper) that intercepts mermaid fenced blocks, calls the Mermaid CLI, and inserts the resulting PNG.

Output paths:

  • Web: SVG (crisp, small, interactive-ready).
  • PDF / EPUB / DOCX: PNG (broadly compatible).

Caching under publications/_cache/mermaid/. Unchanged diagrams do not re-render; full pipeline often completes in under 2 minutes after the first run.

Typst vs. LaTeX

FCC standardized on Typst because:

  • Errors are readable. LaTeX errors are famously opaque.
  • Compile time is much faster.
  • The template language is smaller and more regular.
  • Package management is simpler.

Caveat: Typst is newer. Some advanced typesetting tricks may require LaTeX. For most technical books and reports, Typst is sufficient and preferable.

DOCX output

Editorial workflows sometimes require DOCX (e.g., for copyeditors using track changes in Word). Pandoc handles this. Provide a Word template so the output matches your house style:

format:
  docx:
    reference-doc: templates/house-style.docx

The template is a Word file with your styles defined. Pandoc maps its output to your named styles. The result looks like your brand.

Slides

Two slide targets in FCC: reveal.js (web-native) and PPTX (Microsoft-compatible). Both from the same Markdown:

format:
  revealjs:
    theme: default
    slide-level: 2
  pptx:
    reference-doc: templates/house-style.pptx

Two reasons this matters for docs teams: (a) your marketing team gets PPTX; (b) your conference speakers get reveal.js. One source.

Reference cards

A "reference card" is a one-page, high-density summary. FCC ships five (architecture overview, persona quick-reference, workflow cheat sheet, compliance checklist, glossary).

Each is a Quarto .qmd file configured to render as a single-page PDF with a tighter typographic scale. Useful for handouts, wall posters, and onboarding.

CI integration

The full pipeline runs in CI on release branches. Typical GitHub Actions step:

- uses: quarto-dev/quarto-actions/setup@v2
- run: make pub-all
- uses: actions/upload-artifact@v3
  with:
    name: publications
    path: publications/_output/

Committing _output/ to the repository is a choice: FCC does it from v1.0.3 onward, so readers can view artifacts without running the pipeline. Others prefer to keep _output/ out of git and publish via GitHub Pages / S3. Both are defensible.

Build times

Typical FCC pipeline run:

  • Cold: 8-15 minutes.
  • Warm (cache hit on most Mermaid and rendered chapters): 30-90 seconds.

Budget accordingly. For large teams, add a nightly CI run that rebuilds and pushes to a staging bucket; authors see preview within minutes.

Adopting incrementally

Recommended sequence:

  1. Week 1. MkDocs site + Mermaid rendering for the web.
  2. Week 2-3. One PDF book via Quarto + Pandoc + Typst.
  3. Week 4. EPUB and DOCX targets.
  4. Month 2. Executive / academic profile overlays.
  5. Month 3. Slides + reference cards.

Do not attempt all at once. Each step produces a visible artifact; skip steps that do not fit your audience.

Anti-patterns

  • Rendering twice. One source, many outputs. Never copy a Markdown file to "fit PDF better."
  • Hand-tuned PDFs. If the PDF requires manual touch-ups, your template is wrong; fix the template.
  • Skipping EPUB. EPUB is cheap once PDF works; accessibility stakeholders will thank you.
  • Rendering on laptops only. Always CI-render. Laptop-only is "works on my machine" at publishing scale.

Troubleshooting

  • Typst fails with font error. Install required fonts on the build machine; prefer system fonts bundled with most distros.
  • Mermaid fails intermittently. Chromium instability; retry the build; increase --puppeteer-timeout.
  • EPUB loses styling. Simplify CSS; many readers strip advanced styles.
  • DOCX looks wrong. Check your reference-doc; rebuild with a fresh template.

Where next

With the pipeline in hand, unify your vocabulary via Glossary Governance, or loop back through Mermaid Conventions and Persona-Driven Docs to tighten the input side.