Skip to content

Publications Tutorial Track

Contributor-focused tutorials for extending the FCC publication pipeline — books, Guidebook, executive summary, academic package, reference cards, presentations, and the patent profile.

Who this is for

  • Authors adding new book chapters
  • Contributors fixing broken builds
  • Release managers running make pub-all locally
  • Anyone needing to understand how docs/ source becomes the 27+ artifacts under publications/_output/

Tutorials

# Tutorial Duration Topics
1 Publication Pipeline Mechanics 60 min make pub-all internals, mermaid pre-render, twin trees, Quarto + Pandoc + Typst + mermaid-cli orchestration, patent profile, troubleshooting
2 Adding a New Book Chapter 45 min Chapter stub → _quarto.yml wiring → mermaid diagrams with figure metadata → verification across 4 output formats

Total estimated time: 1 hour 45 minutes

Suggested order

Read the pipeline mechanics first if you have never run make pub-all locally — it gives you the conceptual map. Then apply that map in the contributor workflow by following "Adding a New Book Chapter."

Publication pipeline Makefile targets

Quick reference to the make targets you will use:

Target Purpose
make pub-diagrams Pre-render mermaid to SVG + PNG twin trees
make pub-diagrams-clean Nuke rendered diagram assets
make pub-all Full pipeline — books + all profiles (~10 min warm)
make pub-books Books only (4 × 4 formats = 16 artifacts)
make pub-executive Executive package only (PDF + DOCX)
make pub-academic Academic package only (PDF + EPUB)
make pub-reference Reference cards only (5 PDFs)
make pub-patent Patent profile only (counsel review)
make pub-markdown Markdown publications with embedded diagrams
make pub-clean Nuke entire _output/ + _build/
make pub-diagrams-v15 Render just the 10 v1.5.0-aligned diagrams
make pub-all-v15 Full refresh anchored to v1.5.x state

What you will be able to do

  • Run make pub-all locally and interpret its output
  • Add a new chapter to any of the three books or the Guidebook
  • Embed mermaid diagrams that render correctly as both SVG (PDF/HTML) and PNG (DOCX/EPUB)
  • Diagnose the three most common failure modes: mermaid syntax errors, Chromium sandbox issues on WSL2, and missing fonts
  • Decide when to edit _quarto.yml (only for Quarto profiles) versus relying on the direct-Pandoc path for books
  • Publication scripts — publications/scripts/build_all.sh, publications/scripts/render_mermaid.py
  • Quarto configs — publications/_quarto.yml, publications/_quarto-patent.yml, publications/_quarto-academic.yml, publications/_quarto-executive.yml
  • Makefile — top-level Makefile, targets under the Publishing (Quarto + Pandoc) section