joakimp/pi-devbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): Studio's PDF export needs LaTeX; typst only covers plain pandoc
Lint / skill-floor (push) Successful in 12s
Details
Lint / hadolint (push) Successful in 15s
Details
Lint / doc-drift (push) Successful in 18s
Details
Lint / actionlint (push) Successful in 22s
Details

Browse Source 
The README said /studio-pdf and studio_export_pdf use typst (since v1.4.0)
and that "PDF export from Studio/pandoc works out of the box" (since
v1.9.1). Only the pandoc half is true: pi-studio uses $PANDOC_PDF_ENGINE,
falling back to xelatex, and the image has never set it, so Studio export
fails with "xelatex not found" (seen at v1.6.3 and v1.11.2).

New "PDF export from Studio needs LaTeX" section:
- do not set PANDOC_PDF_ENGINE=typst: pi-studio's LaTeX header is then
  printed as page-1 text while pandoc exits 0
- texlive-xetex alone is not enough (lmodern.sty, ulem.sty, pzdr font);
  texlive-xetex lmodern texlive-plain-generic texlive-fonts-recommended
  works, 37 packages / 491 MB, measured on v1.11.2 + pi-studio 0.10.1 by
  exporting and rendering the page

AGENTS.md and Dockerfile.base comments carry the same claim; not changed.
This commit is contained in:
Joakim Persson
2026-10-15 00:38:25 +02:00
parent 10a8030620
commit 77929b73df
2 changed files with 70 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+27
View File
@@ -66,6 +66,33 @@ base** rather than reusing `base-6f3b20266de1`.
read-only preview, and an on-host `curl` that tells "chain up" (`403`) from
"Studio down or on another port" (empty reply). A remote session hit exactly
that: Studio was started on `18765` while only `8765` is published.
- **README said PDF export from Studio works out of the box. It does not.**
Since v1.4.0 (`67da05b`) the README's Studio section has said that
`/studio-pdf` and `studio_export_pdf` use `typst`. Since v1.9.1
(`6353d59`) the image-tags section has also said that "PDF export from
Studio/pandoc works out of the box". That holds for pandoc run directly
(`pandoc doc.md --pdf-engine=typst -o doc.pdf`), but not for Studio.
pi-studio runs pandoc with `$PANDOC_PDF_ENGINE`, falling back to `xelatex`,
and the image has never set that variable (`git log -S PANDOC_PDF_ENGINE`
finds no commit). So `/studio-pdf` and `studio_export_pdf` fail with
`xelatex not found`. That was seen at v1.6.3 and again at v1.11.2. The
README now says so in both places that made the claim, and adds a
"PDF export from Studio needs LaTeX" section with two warnings and a
working recipe:
- **Setting `PANDOC_PDF_ENGINE=typst` makes it worse.** The error message
suggests it, but pi-studio adds its own LaTeX header to the document
(unless the document sets `header-includes`). Under typst, pandoc exits
0 and prints that header as text above the first heading. Seen in the same PDF through two renderers, MuPDF and
Chromium.
- **`texlive-xetex` alone, which the README offered as the fallback, is
not enough.** The export then still lacks `lmodern.sty`, `ulem.sty`
and the `pzdr` font. Adding `lmodern texlive-plain-generic
texlive-fonts-recommended` makes it work: 37 packages and 491 MB
installed, after `apt-get update`. Measured on v1.11.2 with pi-studio
0.10.1. The exported page was looked at, not only its exit code.
The same claim also appears in `AGENTS.md` ("What we DON'T install") and
in comments in `Dockerfile.base`. Neither is changed here.
## v1.11.2 — 2026-10-14