Peanutbook

Peanutbook is a Markdown-based format for writing books, papers, business plans, and static websites — a structured syntax and project layout for long-form, print-ready documents (textbooks, technical books, memoirs, research papers, business plans, and similar works).

It extends ordinary Markdown with chapter conventions, semantic blocks (>NOTES: … >NOTEE), figures, math, cross-references, multi-language editions, and print metadata. See What is Peanutbook? for the full definition.

The build toolchain (pip install peanutbook) turns Peanutbook source files into PDF, EPUB, DOCX, and static HTML book sites via Pandoc, LaTeX, Lua filters, and the built-in HTML renderer. This repository is that toolchain; Peanutbook uses bubble-build, bubble-convert, bubble-paper, bubble-bizplan, and related CLI tools.

Published wheels are Linux-only for now.

Install the toolchain:

pip install peanutbook

Then from this repo root:

bubble-convert 1
bubble-build --style square
./run.sh    # batch release → books/

See Peanutbook syntax reference for NOTES, chapter format, figures, and includes.

Installation

To install the toolchain from PyPI:

pip install peanutbook

For Linux PDF builds, install the dependencies listed in System requirements.

Usage

Command Line Tools

After installation, you can use the command-line tools:

# Convert a single chapter
bubble-convert 1

# Convert all chapters
bubble-convert

# Build complete book
bubble-build

# Batch release build (full book ×3 variants per lang, optional chapter PDFs, collect to books/)
bubble-batch
bubble-batch --chapters
bubble-batch --lang all --cover 7x10 --cover-provider kdp/paperback
# Same as ./run.sh (wrapper)

# One-off proposal / query letter / sample materials (single Markdown → PDF, Pandoc + LuaLaTeX)
bubble-proposal querytracker/proposal.md --lang en --style square --optimize-pdf --optimize-pdf-quality ebook
# Layout follows common U.S. nonfiction proposal conventions (title page: “Book Proposal”, title, by-line, Submitted by; running header ``RUNTITLE / LastName`` + page #; double-spaced body). Enable by putting a YAML block at the top of the .md with at least ``title`` (optional: ``subtitle``, ``author``, ``date``, ``runtitle``, ``runlastname``). Without ``title`` in YAML, output uses the older compact article style (no extra title page).
# Section headings use blue + light-blue rules (``templates/proposal_book_style.tex``). Default output: ``.pdf`` next to the ``.md``; use ``-o`` to override. ``--style`` is ignored (no chapter squares).
# With ``--optimize-pdf``, English uses Ghostscript only if the Pandoc PDF is ≥300 KB (small proposals often grow after pdfwrite). Chinese (``--lang cn``) uses ``qpdf --optimize-images`` at the same threshold (needs ``qpdf`` on PATH; keeps bookmarks).

# Business Plan builder (single Markdown → PDF, Pandoc + LuaLaTeX)
bubble-bizplan --init                       # Scaffold a default bizplan.md template
bubble-bizplan bizplan.md                   # Build business plan PDF
bubble-bizplan bizplan.md --check-only      # Only validate that required narrative sections are present
bubble-bizplan bizplan.md --strict          # Fail the build if required sections are missing
# Enforces double-spacing, 12pt Times font, 1-inch margins, and validates AI4Biz-compliant sections:
# Problem, AI Solution, AI Technical Feasibility (Data Strategy, AI Architecture, AI Ethics & Safety), Competitive Differentiation (Value Proposition Matrix, Unfair Advantage), and Business Model.
# Supports customization via peanut-biz.config and dynamic cover page generation via --cover-name (e.g., tech-dark, tech-white, minimal-light, corporate-blue).
# Optional cover metadata fields: website, project_title, team_member, school, country_region, contact_email, competition_category.

# Academic / research paper (single Markdown → PDF, Pandoc + LuaLaTeX)
bubble-paper --init                         # Scaffold paper.md with YAML front matter
bubble-paper paper.md                       # Build paper PDF (default A4, numbered sections)
bubble-paper paper.md --two-column          # Two-column article layout
# YAML front matter: title, author, affiliation, abstract, keywords, bibliography (e.g. references.bib).
# Uses templates/paper_style.tex for title block, abstract, and section headings.

# Sample paper fixture (in repo):
#   tests/fixtures/sample_paper.md  +  ./scripts/test_sample_paper.sh  →  tests/output/sample_paper.pdf

# Academic / research paper (single Markdown → PDF, Pandoc + LuaLaTeX)
bubble-paper --init                         # Scaffold paper.md with YAML front matter
bubble-paper paper.md                       # Build paper PDF (default A4, numbered sections)
bubble-paper paper.md --two-column          # Two-column article layout
# YAML front matter: title, author, affiliation, abstract, keywords, bibliography (e.g. references.bib).
# Uses templates/paper_style.tex for title block, abstract, and section headings.

# Sample paper fixture (in repo):
#   tests/fixtures/sample_paper.md  +  ./scripts/test_sample_paper.sh  →  tests/output/sample_paper.pdf

# Scaffold a new bubble-compatible project in current folder (asks for confirmation)
bubble-scaffold
bubble-scaffold --chapters 10 --lang both
bubble-scaffold --lang en
bubble-scaffold --lang zh --yes
# Also creates cover/7x10/ with placeholder cover_front.pdf and cover_back.pdf

# Merge chapter markdown into book.md / book_zh.md / … (run from the book repo root)
bubble-merge
bubble-merge --en-only
bubble-merge --zh-only          # Simplified Chinese (cn)
bubble-merge --lang tc          # Traditional Chinese
# Default: auto-detect languages (locales.langs_for_merge); warns on partial translations

# Split a built PDF into N parts for upload (needs qpdf; page count: pdfinfo or PyPDF2)
bubble-split-pdf
bubble-split-pdf book_zh_square.pdf -n 5
bubble-split-pdf --dry-run

# Whole-line *single-star* emphasis checker (excludes chapter title line 3); --write fixes to _underscore_
bubble-single-star
bubble-single-star --include-merged

Other installed commands map to scripts/*.py (same flags as python3 scripts/<name>.py …). Run without arguments or with -h / --help where supported to see usage.

Command	Script
bubble-batch	batch_build.py (package bubble.batch_build) — multi-lang release orchestration
bubble-build	build_book.py (package bubble.build_book)
bubble-proposal	proposal.py (package bubble.proposal)
bubble-bizplan	bizplan.py (package bubble.bizplan) — build structured Business Plan PDF
bubble-paper	paper.py (package bubble.paper) — build academic / research paper PDF
bubble-convert	convert.py (package bubble.convert)
bubble-convert-parts	convert_parts_to_pdf.py — part opener PDFs from partN.md
bubble-monitor	monitor.py (package bubble.monitor)
bubble-scaffold	scaffold.py (package bubble.scaffold)
bubble-add-code-annotations	add_code_annotations.py
bubble-add-math-summaries	add_math_summaries.py
bubble-add-watermark	add_watermark.py
bubble-bold-headings	check_bold_headings.py
bubble-check	colon_list_check.py
bubble-pdfcheck	pdfcheck.py
bubble-convert-svg-text	convert_svg_foreignobject_to_text.py
bubble-count-chars	count_chars.py
bubble-extract-chapter-title	extract_chapter_title_quote.py
bubble-fix-table-width	fix_table_width.py
bubble-fix-zh-period	fix_zh_period.py
bubble-fix-zh-punct	fix_zh_punctuation.py
bubble-fix-zh-quotes	fix_zh_curly_quotes.py
bubble-gen-cover-bg	generate_cover_background.py (needs matplotlib, numpy)
bubble-gen-latex-header	generate_latex_header.py
bubble-gen-toc	generate_toc.py
bubble-image	image_clean.py — chapter PNGs with matching .py, plus cover/*/out
bubble-index	add_index_terms.py
bubble-latex-multi-pass	latex_multi_pass.py
bubble-merge	merge_books.py
bubble-process-code-annotations	process_code_annotations.py
bubble-process-code-explain	process_code_explain.py
bubble-process-includes	process_includes.py
bubble-protect-pdf	protect_pdf.py
bubble-reorder-cover-preface	reorder_cover_preface.py
bubble-set-image-dpi	set_image_dpi.py
bubble-single-star	check_single_star_lines.py
bubble-split-pdf	split_book_pdf.py

# EPUB or Word (Pandoc only; no print template / Lua filters — math and layout may differ from PDF)
bubble-build --format epub
bubble-build --format docx
bubble-build --lang cn --format epub    # writes book_zh.epub

# Optional: DOCX styling — put reference.docx in the project root (or margins/reference_submission.docx)
# Standalone margins/poetry: bubble-convert margins/poem.md -f docx
# Header/footer: peanut.config "docx_footer_text", "docx_footer_text_position" (default top-right),
# "docx_page_number" (default true), "docx_page_number_position" (default bottom-right)
# Optional: EPUB cover — cover_front.png or cover_front.jpg in the active cover/ folder
# Optional: EPUB stylesheet — put epub.css in the project root (overrides bubble default epub.css)
# Legacy .doc: open book.docx in Word/LibreOffice and save as .doc

# With options
bubble-convert 1 --style square --template lulu_7x10
bubble-convert 1 --style square --optimize-pdf --optimize-pdf-quality ebook  # en/sp: Ghostscript; cn/tc/jp: qpdf
bubble-build --max-chapters 21 --style circle

# English body font (LuaLaTeX / fontspec); install the font on the system first
bubble-convert 1 --main-font "Roboto Mono"
bubble-convert 1 --main-font "EB Garamond" --body-font-pt 11
bubble-build --main-font "TeX Gyre Termes"
bubble-build --main-font "EB Garamond" --body-font-pt 11
# Or set "main_font" / "body_font_pt" in peanut.config (overridden by CLI when passed)

# Chapter styles: circle (quarter-circle), square (blue square), none (no decoration)
bubble-build --style none

# Select cover folder
bubble-build --cover 7x10-packt
bubble-build --cover 7x10
bubble-build --cover 8.5x11

# Shrink final PDF after build: en/sp use Ghostscript pdfwrite (``gs`` on PATH; ``--optimize-pdf-quality``).
# CJK locales (cn/tc/jp) use ``qpdf --optimize-images`` (``qpdf`` on PATH) to avoid destroying XeLaTeX outlines.
bubble-build --optimize-pdf
bubble-build --optimize-pdf --optimize-pdf-quality prepress   # English only: less aggressive Ghostscript compression

# Do not expect a small book.pdf if you also use --protect: protection rasterizes each page
# (default 300 DPI), so the PDF is mostly embedded images (often tens of MB). For Lulu/POD
# uploads use --optimize-pdf without --protect, or lower size with e.g. --protect-dpi 150.

# KDP paperback and hardcover (interior-only PDF, no cover, no chapter decoration)
bubble-build --no-cover --style none

# Batch release (Math4AI-style: cover + square interior + none interior per lang; optional chapter PDFs)
bubble-batch
bubble-batch --chapters
bubble-batch --lang en --cover 7x10 --cover-provider ingram/hardcover --cover-version v2
bubble-batch --lang en,cn,tc --style none
bubble-batch --lang all --optimize-pdf
# Collects book*.pdf and chapter*.pdf into books/ (override with --output-dir)
# Project root ./run.sh is a thin wrapper: exec bubble-batch "$@"

bubble-batch peanut.config keys (optional; merged with peanut.config.default):

Key	Purpose
batch_default_langs	JSON array, e.g. ["cn", "tc", "en"]. Used when no LANG args, or when LANG is all. If omitted, default is single lang (or every scanned language for all).
batch_book_ads	Footer text for protected per-chapter PDFs (--ads).
batch_output_dir	Collect directory (default: books).
batch_cover_style	Cover-build style: circle, square, or none. Interior builds stay square + none.
batch_chapter_style	Style for --chapters per-chapter PDFs.
batch_optimize_pdf	Boolean (default false). Set true or pass --optimize-pdf to enable; --no-optimize-pdf forces off.
batch_optimize_pdf_quality	screen, ebook, printer, or prepress (default ebook).

Example (multi-language memoir):

{
  "batch_default_langs": ["cn", "tc", "en"],
  "batch_book_ads": "Above The Clouds - Xuan Xin",
  "chapter_style": "square"
}

Per-chapter builds (--chapters) always use the highest chapter number found under chapter*/chapter*.md.

Python API

You can also use the package programmatically:

from bubble.convert import Converter, ChapterStyle, BuildMode
from pathlib import Path

# Create converter
converter = Converter(
    project_root=Path.cwd(),
    chapter_style=ChapterStyle.CIRCLE,
    mode=BuildMode.DEV,
    # Optional: main_font="EB Garamond", body_font_pt="11"
)

# Convert a chapter
converter.convert("1")

# Or convert all chapters
converter.convert()

from bubble.build_book import BookBuilder, ChapterStyle
from pathlib import Path

# Create builder
builder = BookBuilder(
    project_root=Path.cwd(),
    chapter_style=ChapterStyle.CIRCLE,
    max_chapters=21,
    # output_format="epub",  # or "docx"; default "pdf"
)

# Build the book
builder.build()

Features

• Chapter Conversion: Convert individual markdown chapters to PDF
• Book Building: Merge all chapters into a complete book with automatic TOC
• EPUB / DOCX: bubble-build --format epub or --format docx exports via Pandoc (see Usage)
• Template Support: Support for different page sizes (Amazon KDP, A4, etc.)
• Cover Selection: Select which cover folder to use with --cover option
• Watermarking: Add text or image watermarks to PDFs
• PDF Protection: Protect PDFs from copying and OCR
• Image Generation: Automatically run Python scripts in chapter img directories
• Part PDFs: Support for inserting part PDFs between chapters
• Appendix Support: Handle appendix chapters
• Multi-language builds: English plus localized editions via --lang and per-locale markdown suffixes (see below)

Multi-language support

Bubble can build the same book in several languages. Each edition uses a runtime language code (--lang or peanut.config "lang") paired with a markdown file suffix for translated chapters. English sources have no suffix.

--lang	Markdown suffix	Merged book	PDF example (--style square)
en	(none) chapterN.md	book.md	book_square.pdf
cn	_zh	book_zh.md	book_zh_square.pdf
tc	_tc	book_tc.md	book_tc_square.pdf
jp	_jp	book_jp.md	book_jp_square.pdf
sp	_sp	book_sp.md	book_sp_square.pdf

Note: cn is the code for Simplified Chinese; source files still use the _zh suffix (historical naming). bubble-scaffold --lang zh creates *_zh.md and sets "lang": "cn" in peanut.config.

Source layout

Localized markdown lives beside English in the same chapter folders (no separate locale/ tree):

project_root/
├── chapter1-vector-space/chapter1.md      # English
├── chapter1-vector-space/chapter1_zh.md   # Simplified Chinese (cn)
├── chapter1-vector-space/chapter1_tc.md   # Traditional Chinese (tc)
├── chapter1-vector-space/chapter1_jp.md   # Japanese (jp)
├── chapter1-vector-space/chapter1_sp.md   # Spanish (sp)
├── chapterx/preface.md
├── chapterx/preface_zh.md
├── chapterx/preface_tc.md
├── …
├── chapterx/chapterx.md                   # appendix (en)
├── chapterx/chapterx_zh.md
└── img/                                   # shared across languages

If a localized file is missing for a chapter, the build falls back to the English chapterN.md for that chapter (same behavior as partial _zh coverage today).

Commands

# Full book (set default in peanut.config: "lang": "tc")
bubble-build --lang tc
bubble-build --lang jp --style square
bubble-build --lang sp --no-cover --style none

# Single chapter
bubble-convert 3 --lang jp

# Merge translated markdown for editing / review
bubble-merge --zh-only              # book_zh.md (cn)
bubble-merge --lang tc              # book_tc.md
bubble-merge --lang jp

# Watch and auto-rebuild localized chapters
bubble-monitor --lang tc 1 2 3

# Proposals / sample pages with CJK fonts
bubble-proposal notes/sample.md --lang jp

EPUB/DOCX follow the same naming: e.g. bubble-build --lang tc --format epub → book_tc.epub.

Typography and PDF tooling

Locales	LaTeX engine	Fonts	--optimize-pdf
en, sp	LuaLaTeX	Latin (--main-font allowed)	Ghostscript pdfwrite (gs on PATH)
cn, tc, jp	XeLaTeX	Noto Serif CJK SC / TC / JP	qpdf --optimize-images (keeps CJK bookmarks)

Install CJK fonts on the build machine (e.g. fonts-noto-cjk on Debian/Ubuntu). Spanish uses standard Latin fonts and Spanish TOC/chapter strings (Índice, Capítulo).

Covers and config

Optional per-locale cover PDFs in the active cover folder (e.g. cover/7x10/):

• cover_front_zh.pdf / cover_back_zh.pdf (and _tc, _jp, _sp variants)

Override appendix divider titles in peanut.config:

• appendix_divider_title_en, appendix_divider_title_cn, appendix_divider_title_tc, appendix_divider_title_jp, appendix_divider_title_sp

enable_chinese_body_font_bump applies to all CJK locales (cn, tc, jp) when enabled.

Editorial helpers (Chinese)

bubble-fix-zh-period, bubble-fix-zh-punct, and bubble-fix-zh-quotes target *_zh.md only. Extend or duplicate those workflows for _tc.md / _jp.md as needed; Japanese punctuation rules differ from Chinese.

Locale metadata is centralized in bubble/locales.py (VALID_LANGS, fonts, UI strings, output stems).

Cover Selection

The build system automatically selects a cover folder based on your template (7×10 is the default size for color):

• lulu_7x10.tpl or amazon_7x10.tpl → cover/7x10/
• a4_8.5x11.tpl → cover/8.5x11/

Before using cover PDFs, bubble-build runs all Python scripts (e.g. cover_front.py, cover_back.py) in that folder so that front/back cover PDFs are generated for the chosen size. If you specify a different folder with --cover, scripts in that folder are run instead.

You can override the cover folder with the --cover option:

# Use Packt-style covers (runs Python files in cover/7x10-packt/)
bubble-build --cover 7x10-packt

# Use default 7x10 covers (runs Python files in cover/7x10/)
bubble-build --cover 7x10

# Use 8.5x11 covers (runs Python files in cover/8.5x11/)
bubble-build --cover 8.5x11

The system then looks for cover_front.pdf and cover_back.pdf in the specified folder:

1. First checks cover/{cover_folder}/cover_front.pdf
2. Falls back to cover/cover_front.pdf (for backward compatibility)
3. Finally checks cover_front.pdf in project root

This allows you to maintain multiple cover designs and easily switch between them.

Requirements

• Python 3.12+
• Pandoc
• LaTeX (lualatex, xelatex, or pdflatex)
• makeindex (for keyword index)

Project Structure

The package expects a project structure like:

project_root/
├── chapter1-*/chapter1.md
├── chapter1-*/chapter1_zh.md   # optional localized chapters (_tc, _jp, _sp, …)
├── chapter2-*/chapter2.md
├── ...
├── chapterx/preface.md
├── chapterx/chapterx.md        # appendix (en)
├── chapterx/preface_zh.md        # optional
├── book.md                     # merged English (bubble-merge)
├── book_zh.md                  # merged cn, etc.
├── cover/            # Cover PDFs
│   ├── 7x10/         # Default cover folder (for lulu_7x10 / amazon_7x10 templates)
│   │   ├── cover_front.pdf
│   │   ├── cover_front_zh.pdf  # optional per locale
│   │   └── cover_back.pdf
│   ├── 7x10-packt/   # Packt-style covers
│   │   ├── cover_front.pdf
│   │   └── cover_back.pdf
│   └── 8.5x11/       # A4/8.5x11 covers
│       ├── cover_front.pdf
│       └── cover_back.pdf
└── peanut.config     # Configuration file

Configuration

Create a peanut.config file in your project root. You can use the default config file included in the package as a starting point:

# Copy the default config to your project root
cp $(python -c "import bubble; import os; print(os.path.dirname(bubble.__file__))")/peanut.config.default ./peanut.config

Or create your own peanut.config file. Values merge with the package peanut.config.default (project keys override). A minimal file can set only what differs from defaults.

{
  "lang": "en",
  "chapter_style": "circle",
  "template": "amazon_7x10.tpl",
  "book_title": "Your Book Title",
  "conda_env": "your_env_name",
  "include_math": true,
  "include_numpy": false,
  "include_torch": false
}

lang is optional (en, cn, tc, jp, or sp). When set, it becomes the default for bubble-build and bubble-convert when you omit --lang (CLI --lang still overrides). See Multi-language support above.

chapter_style is optional (circle, square, or none). Same as --style / -s when omitted; you may also set style as an alias for chapter_style. CLI --style overrides.

Print layout switches (peanut.config)

These options affect PDF output (LaTeX header, pandoc geometry, Lua filters). Defaults in peanut.config.default favor legacy / piggy-like behavior for Amazon 7×10; turn flags on for newer “main branch” styling.

Key	Role
enable_spot_heading_layout	If false (default), generate_latex_header.py strips the BUBBLE_SPOT_HEADING_* block so section titles use book.cls defaults (matches older templates that had no spot block). If true, keeps the spot/titlesec block in amazon_7x10.tpl / siblings.
enable_styled_subsection_lua	If true, prepends styled_subsection.lua when spot layout is also enabled. Default false (piggy did not use this filter).
enable_chapter_titlepage_odd_page	If true, each chaptertitlepage and part opener (\includepdf of partN.pdf) starts on a recto (odd) page via \BubbleForceOddPage. Default false (\newpage only).
enable_pod_safe_margins	If false (default), 7×10 geometry uses legacy margins (book_config.GEOMETRY_AMAZON_7X10_LEGACY). If true, uses wider POD-style margins (GEOMETRY_AMAZON_7X10_POD).
enable_peanut_font_settings	If false (default), @@…@@ font placeholders in templates are filled with built-in defaults (same numbers as legacy hard-coded templates). If true, sizes come from the numeric keys in merged peanut.config (e.g. chapter_title_font_size_pt).
enable_english_body_font_bump	Optional larger English \normalsize (off by default).
enable_chinese_body_font_bump	Larger CJK body size when lang is cn, tc, or jp (on by default in peanut.config.default).

Templates and defaults: bubble-build / bubble-convert default to amazon_7x10.tpl when no template is set (merged config and CLI --template override). Use lulu_7x10.tpl or a4_8.5x11.tpl when you need those trim sizes.

License

See the main project license.