docs: Studio's PDF export needs LaTeX, in AGENTS.md and Dockerfile.base too
Lint / skill-floor (push) Successful in 9s
Lint / hadolint (push) Successful in 12s
Lint / doc-drift (push) Successful in 14s
Lint / actionlint (push) Successful in 22s

AGENTS.md ("What we DON'T install") and two comments in Dockerfile.base's
typst block still said pi-studio's PDF export uses typst. Same correction
as 77929b7 for the README. AGENTS.md also warns maintainers not to ship
ENV PANDOC_PDF_ENGINE=typst, since pi-studio's LaTeX header is printed as
page text under typst while pandoc exits 0.

Corrects 77929b7: "texlive-xetex alone is not enough" holds only with
--no-install-recommends. With apt's defaults, texlive-xetex (and the old
AGENTS recipe, texlive-xetex texlive-latex-recommended: the same set) works,
but installs 202 packages / 1053 MB including systemd, D-Bus and a JRE.
The README recipe (4 packages, --no-install-recommends) is 37 / 491 MB.
All three recipes measured from the image's 401 packages on v1.11.2 +
pi-studio 0.10.1, checking the exported page, not only the exit code.

Dockerfile.base changes are comments only, but base_tag hashes the whole
file; the next release rebuilds the base anyway.
This commit is contained in:
2026-10-15 01:04:40 +02:00
parent 77929b73df
commit 5becbba6c8
4 changed files with 54 additions and 27 deletions
+18 -8
View File
@@ -354,14 +354,24 @@ deprecated artifacts (to be removed in opencode-devbox v2.0.0).
## What we DON'T install (and why)
- **No texlive** (~600 MB–1 GB). PDF export from pandoc / pi-studio works
out of the box via **`typst`** (~30 MB static binary), which the base ships
as the pandoc PDF engine (`pandoc --pdf-engine=typst`) — small enough to live
in base rather than a dedicated `:latest-studio-tex` variant. We don't bake in
a full TeX Live: it's heavy and typst covers the common Markdown→PDF case.
Users needing LaTeX-exact output can install the higher-fidelity fallback on
demand: `sudo apt-get install texlive-xetex texlive-latex-recommended` (then
`pandoc --pdf-engine=xelatex`).
- **No texlive** (~0.5–1 GB). The base ships **`typst`** (~30 MB static
binary) as a PDF engine for pandoc, so
`pandoc doc.md --pdf-engine=typst -o doc.pdf` works out of the box. That
covers the common Markdown→PDF case, small enough to live in base rather
than in a dedicated `:latest-studio-tex` variant. Callers must ask for
typst: pandoc's own default engine is `pdflatex`, which is not installed.
**pi-studio's PDF export (`/studio-pdf`, `studio_export_pdf`) does not use
typst.** It runs pandoc with `$PANDOC_PDF_ENGINE`, defaulting to `xelatex`,
so in this image it fails with `xelatex not found`. Do not "fix" that with
`ENV PANDOC_PDF_ENGINE=typst`. pi-studio adds its own LaTeX header to the
document, and typst prints that header as page text while pandoc exits 0.
That ENV only becomes a fix once pi-studio stops sending its LaTeX header
to non-LaTeX engines. Until then, users who need Studio's PDF export, or
LaTeX output, install TeX Live on demand with the recipe in README
"PDF export from Studio needs LaTeX" (37 packages, ~490 MB with
`--no-install-recommends`). A plain `sudo apt-get install texlive-xetex`
also works, but its recommends make it 202 packages and ~1 GB, including
systemd and a Java runtime.
- **pi-studio** ships in the `:latest-studio` variant (since v1.1.0),
vendored to `/opt/pi-studio` and registered at container start via
`pi install /opt/pi-studio` (see Dockerfile.variant `INSTALL_STUDIO`).