System requirements¶

Platform¶

The peanutbook toolchain is supported on Linux only (Debian/Ubuntu and similar distributions). Examples below use apt; adapt package names for your distro.

Python¶

Python 3.9+ (3.12 recommended)
Package dependency: watchdog (file monitor); release wheels also use pyzipper

Required for PDF builds¶

Tool	Purpose
Pandoc	Markdown → LaTeX / EPUB / DOCX
LuaLaTeX	English and Spanish PDF
XeLaTeX	Chinese, Traditional Chinese, Japanese PDF
makeindex	Keyword index (`bubble-index`)

Install TeX on Debian/Ubuntu:

sudo apt install texlive-full
# or a smaller set: texlive-luatex texlive-xetex texlive-latex-extra

Fonts¶

Locale	Font
`en`, `sp`	Any OpenType font via `--main-font` / `main_font` in config
`cn`	Noto Serif CJK SC
`tc`	Noto Serif CJK TC
`jp`	Noto Serif CJK JP

Debian/Ubuntu: fonts-noto-cjk

Optional tools¶

Tool	Used by
Ghostscript (`gs`)	`--optimize-pdf` for English/Spanish
qpdf	`--optimize-pdf` for CJK; `bubble-split-pdf`
PyPDF2 or pdfinfo (poppler)	Page count for split PDF
pdftotext (poppler-utils)	`bubble-pdfcheck` — scan built PDFs for `??` and leaked labels
matplotlib, numpy	`bubble-gen-cover-bg`
Conda env named in config	Running figure scripts in `chapter*/img/`
mmdc or Node.js (`npx`)	Mermaid diagrams in PDF, DOCX, EPUB, and HTML

Mermaid diagrams (optional)¶

Mermaid is optional — only needed when your book uses ```mermaid fenced blocks. PDF, DOCX, EPUB, and HTML render diagrams to PNG at build time via mermaid-cli (mmdc).

Install Node.js (if you do not have `mmdc`)¶

Debian/Ubuntu:

sudo apt install nodejs npm
# Node 18+ recommended; use NodeSource if the distro package is too old:
# https://github.com/nodesource/distributions
node --version

Option A — global `mmdc` (recommended for frequent builds)¶

npm install -g @mermaid-js/mermaid-cli
mmdc --version
which mmdc

Option B — `npx` (no global install)¶

If mmdc is not on PATH but npx is available, Peanutbook runs:

npx -y @mermaid-js/mermaid-cli …

The first diagram render may download the CLI package (network required).

What Peanutbook needs¶

Output	Peanutbook	Mermaid CLI	Pandoc / LaTeX
HTML (`bubble-render-html`)	`pip install peanutbook`	Yes (`mmdc` or `npx`)	No
DOCX (`bubble-convert --format docx`, `bubble-build --format docx`)	`pip install peanutbook`	Yes	Pandoc only
EPUB (`bubble-build --format epub`)	`pip install peanutbook`	Yes	Pandoc only
PDF	`pip install peanutbook`	Yes	Yes

Rendered PNGs are cached under img/.mermaid/ next to each chapter (content-hash filenames). No extra peanut.config keys are required.

If Mermaid is not installed, builds may leave the fence as a code block instead of a figure.

EPUB / DOCX¶

EPUB and DOCX exports use Pandoc (no LaTeX). ```mermaid fences are rendered to embedded PNG figures, same as PDF. Math and layout may differ from print PDF. For Word, optionally provide reference.docx in the project root.

Documentation site¶

User documentation is published at peanutbook.readthedocs.io. It is built from the public peanutbook-docs repository (Markdown + MkDocs config only, no Python source). Install the product via pip install peanutbook, not from a public Git clone.