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

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:
2026-10-15 00:38:25 +02:00
parent 10a8030620
commit 77929b73df
2 changed files with 70 additions and 8 deletions
+43 -8
View File
@@ -175,10 +175,12 @@ Currently published:
| `joakimp/pi-devbox:latest-studio` | `latest` + [pi-studio](https://github.com/omaclaren/pi-studio) (browser prompt editor, KaTeX/Mermaid preview, tmux-backed literate REPLs) | ~3.25 GB |
| `joakimp/pi-devbox:vX.Y.Z-studio` | pinned-version studio equivalent | ~3.25 GB |
Both variants ship **`typst`** as the pandoc PDF engine
(`pandoc --pdf-engine=typst`), a single ~30 MB static binary, so PDF export from
Studio/pandoc works out of the box — no separate `-tex` variant needed.
`texlive-xetex` stays the higher-fidelity fallback (install on demand).
Both variants ship **`typst`**, a single ~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 (see [Generating a PDF with pandoc + typst](#generating-a-pdf-with-pandoc--typst)).
**pi-studio's PDF export does not use typst.** `/studio-pdf` and
`studio_export_pdf` need a LaTeX engine, which neither variant ships (see
[PDF export from Studio needs LaTeX](#pdf-export-from-studio-needs-latex)).
## Using pi-studio (`-studio` variant)
@@ -345,10 +347,43 @@ Assuming the compose file publishes `127.0.0.1:8765:8765` (see method B):
> an empty reply means the bridge has nothing behind it, i.e. Studio is down
> or on another port.
> PDF export (`/studio-pdf`, `studio_export_pdf`) uses **`typst`**, shipped in
> the base image as the pandoc PDF engine (`pandoc --pdf-engine=typst`). For
> LaTeX-exact output you can install `texlive-xetex` on demand as a heavier
> fallback. HTML export, KaTeX, Mermaid, and all REPL features work regardless.
### PDF export from Studio needs LaTeX
Studio's PDF export (`/studio-pdf` and the `studio_export_pdf` tool) fails out
of the box:
```text
pandoc PDF export failed with exit code 47: xelatex not found
```
pi-studio runs pandoc with the engine named in `PANDOC_PDF_ENGINE`, and uses
`xelatex` when that is unset. The image ships no LaTeX engine and does not set
`PANDOC_PDF_ENGINE`. HTML export, KaTeX, Mermaid and the REPLs are not
affected.
**Do not set `PANDOC_PDF_ENGINE=typst`**, even though the error message
suggests setting it. pi-studio adds its own LaTeX header
(`\usepackage{titlesec}`, `\titleformat…`) to the document, and typst does
not understand LaTeX. pandoc exits 0, and the header is printed as text above
your first heading. There is no error, only a wrong PDF.
There are two ways out:
- **Run pandoc yourself** (nothing to install):
`pandoc doc.md --pdf-engine=typst -o doc.pdf`. See the next section.
- **Install the LaTeX packages Studio needs.** This adds 37 packages and
about 490 MB, and they are gone when the container is recreated:
```bash
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
texlive-xetex lmodern texlive-plain-generic texlive-fonts-recommended
```
`texlive-xetex` on its own is not enough. Studio's export then still lacks
`lmodern.sty`, `ulem.sty` and the `pzdr` font, which come from the other
three packages. The image starts with an empty package index, so run
`apt-get update` first. (Measured on v1.11.2 with pi-studio 0.10.1.)
### Generating a PDF with pandoc + typst