docs(readme): Studio's PDF export needs LaTeX; typst only covers plain pandoc
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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user