v2.0.0 — diagrams, math, multi-file documents

This is the biggest release doc-engine has had. Diagrams, math, and multi-file
documents are the headline, but a fair amount of it is fixing things that had
been quietly wrong for a long time.

Diagrams

Fenced mermaid and svg blocks are rendered as real diagrams instead of
code. Mermaid runs on an embedded JavaScript engine, so there is still no Node
to install and no headless browser — it stays a plain pip install. A diagram
with a syntax error stops the build and shows Mermaid's own message rather than
producing a broken document.

Closes #8.

Math

LaTeX math is translated into native Typst math, inline with $…$ and as a
block with $$…$$. Greek letters, relations, fractions, roots, scripts, font
commands, matrices, and cases are covered, along with logic, floors and
ceilings, big operators, arrows, and vector accents.

A $ that is not math stays untouched, so $10, $HOME, and export $PATH
survive. That one is worth stating plainly: enabling math naively would have
mangled almost every README out there.

Multi-file documents

A project that outgrew a single file lists its parts in a doc-engine.md
manifest, written as ordinary Markdown links so it still reads as a table of
contents on GitHub:

---
title: Payments Platform
template: report
---

- [Overview](doc/overview.md)
- [Architecture](diagrams/flow.mmd)
- [Schema](img/schema.svg)
- [References](bib/refs.bib)

Markdown files become sections, .mmd files are rendered where they appear,
images are placed as captioned figures, and a .bib becomes the bibliography.
A link from one included file to another jumps inside the PDF instead of
pointing at a file the reader does not have. Watch mode follows every file the
manifest names.

Two new layouts

article is a classic LaTeX paper — New Computer Modern, numbered sections, a
title block instead of a cover sheet. report trades density for legibility:
12pt on generous leading, wide margins, a lot of air. That makes seven.

Page sizes

A4 is now the default. This is the breaking change. us-letter is the
standard in the US and Canada and nowhere else, and it was hardcoded into every
template. --paper us-letter gets the old behaviour back, and A3 through A6,
ISO and JIS B5, US legal, and tabloid are all there too.

Alerts

> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] render as
coloured callouts, the way GitHub shows them.

Code themes

--code-theme github, solarized, or monochrome, or a path to any TextMate
.tmTheme from your editor. The monochrome one exists because code printed in
black and white loses meaning when colour is the only thing separating a
keyword from a string.

Project configuration

A .doc-engine.toml, or a [tool.doc-engine] table in pyproject.toml, holds
a team's defaults so they are not repeated in every document. A flag beats
front matter, which beats the file.

Everything else

• Archival output with --pdf-standard a-2b or a-3b
• Remote images with --fetch-images, off by default, bounded by a timeout
  and a size ceiling
• Tall images either scale onto one page or split across several with
  --tall-images split
• --subtitle, --date, --force, and a --help that finally shows the
  build flags grouped by what they affect instead of hiding them behind
  build --help
• info --json for anything driving the CLI

Fixes, including some old ones

Four of these predate this release:

• Tables with more than one column collapsed into one. Since 1.0.0. Every
  table in every PDF this tool produced was wrong.
• Tall images were silently clipped. The bottom of a long diagram just did
  not make it into the document.
• Templates asked for fonts that do not exist in the published Docker image,
  so documents built there quietly used something else. Every font stack now
  ends in one Typst ships.
• Legacy Windows consoles crashed on the arrows and checkmarks in the
  output.

And from this release: a repeated tall image left a dangling reference, front
matter inside an included file was rendered as body text, and figure captions
were not escaped.

On the first diagram taking a while

Rendering the first Mermaid diagram in a run takes about nine seconds while the
JavaScript engine starts. Every diagram after that takes about a tenth of a
second. It now says so while it waits, instead of sitting on a spinner that
looks like a hang. Under --watch it happens once and never again.

Upgrading

pipx upgrade doc-engine-cli

The only thing that changes for an existing document is the page size. If you
want US Letter, pass --paper us-letter or put paper = "us-letter" in a
.doc-engine.toml.

229 tests, on Python 3.10 through 3.14, across Linux, macOS, and Windows.

Full Changelog: v1.1.1...v2.0.0