feat(publish): replace publishing system with Quarto

[vanandrew]

Summary

Replaces jamb's document publishing system with a single, Quarto-based pipeline. The previous design had two independently hand-maintained renderers — publish/formats/html.py (raw string concatenation) and publish/formats/docx.py (manual python-docx OXML) — with Markdown handled separately in the CLI. This is a ground-up replacement: the old publish/formats/ package is deleted and the new code stands on its own.

Requirement items now flow through one model → Quarto markdown (.qmd) → Quarto, which renders HTML, DOCX, and PDF. Markdown and raw .qmd are written directly without invoking the binary.

What's new

• PDF output via Quarto's bundled Typst engine (no LaTeX) — the original motivation.
• Table of contents and consistent, professional styling across all formats.
• Working cross-references: item links resolve to HTML anchors, DOCX bookmarks, and PDF internal links automatically (replacing the hand-rolled bookmark/hyperlink OXML).
• Data-driven styling: a bundled SCSS theme (HTML) and a Word reference document, both overridable with --template. jamb template now scaffolds these editable assets into ./jamb-assets/.

Architecture

src/jamb/publish/ is split into a pure layer and a render layer:

• formats.py — OutputFormat enum + extension mapping
• document.py — build_publish_document() → ordered PublishDocument (pure)
• qmd.py — PublishDocument → .qmd source via Jinja2 (pure, unit-tested without the binary)
• quarto.py — locate/run the Quarto binary; typed errors
• render.py — generate .qmd in a temp dir and invoke Quarto
• assets/ — bundled document.qmd.j2 and theme.scss

CLI

jamb publish PREFIX [PATH] gains --pdf; --template is now format-aware (SCSS / reference .docx / Typst template). .pdf and .qmd are auto-detected from the extension. jamb template scaffolds the styling assets instead of generating a .docx.

Dependencies

• Removed python-docx.
• Added quarto-cli as a core dependency (per design decision — publishing works out of the box).
• jinja2 is now actually used (previously declared but unused).

⚠️ Note on footprint: the quarto-cli PyPI package downloads the ~150 MB Quarto binary at install time and hard-depends on jupyter/nbclient (jamb never executes notebooks, but the tree installs regardless). This meaningfully increases install size and uv sync time for every install, including pytest-plugin-only users. CI now enables uv caching so the build isn't repeated each run. Flagging in case we'd prefer an optional jamb[publish] extra instead — easy to switch.

Tests

• Deleted the old HTML/DOCX byte-assertion unit tests.
• Added tests/unit/test_publish_qmd.py — pure tests for the document model, .qmd generation, markdown escaping, format mapping, and binary resolution (no Quarto needed).
• Added tests/integration/test_publish_render.py — real renders asserting magic bytes and surviving anchors, marked @pytest.mark.quarto.
• Render-producing CLI/integration tests are marked quarto and auto-skip when the binary is absent (conftest hook).
• Full suite: 1471 passed, 1 skipped; ruff, ruff-format, and ty all clean.

Docs

Updated the publishing guide, command reference, tutorial, installation, design, FAQ, troubleshooting, API reference, README, and CONTRIBUTING to describe the Quarto pipeline and PDF output.

Verification

• uv sync && uv run quarto --version → resolves
• uv build --wheel → bundles publish/assets/*
• Manual: jamb publish all out.{html,docx,pdf,md,qmd} all render; jamb template scaffolds theme + reference doc; --template overrides apply.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 85.26646% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.92%. Comparing base (9d6b03d) to head (2691f68).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/jamb/cli/commands.py	85.00%	11 Missing and 4 partials ⚠️
src/jamb/publish/quarto.py	68.18%	12 Missing and 2 partials ⚠️
src/jamb/publish/docx_reference.py	80.95%	6 Missing and 2 partials ⚠️
src/jamb/publish/render.py	88.37%	2 Missing and 3 partials ⚠️
src/jamb/publish/document.py	85.18%	2 Missing and 2 partials ⚠️
src/jamb/publish/qmd.py	98.07%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #33      +/-   ##
==========================================
- Coverage   91.84%   90.92%   -0.93%     
==========================================
  Files          27       31       +4     
  Lines        3852     3770      -82     
  Branches      867      857      -10     
==========================================
- Hits         3538     3428     -110     
- Misses        198      221      +23     
- Partials      116      121       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.