bubble-book 0.0.1.dev0

Book Building Utilities - Convert markdown chapters to PDF and build complete books

Peanutbook

Peanutbook is a book project in the Peanutbook format — Markdown chapters plus peanut.config, built with bubble-book.

Install the toolchain:

pip install bubble-book

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

Option 1: Editable Install (Recommended)

cd shared/bubble
pip install -e .

Option 2: With --user flag (macOS Homebrew Python)

If you encounter an "externally-managed-environment" error:

cd shared/bubble
pip install -e . --user --break-system-packages

Option 3: Configure pip.conf (Permanent Solution)

Add to ~/.pip/pip.conf (or ~/.config/pip/pip.conf on macOS):

[global]
break-system-packages = true
user = true

Then install normally:

cd shared/bubble
pip install -e .

Option 4: Conda Environment

# Create and activate conda environment
conda create -n bubble python=3.12
conda activate bubble

# Install the package
cd shared/bubble
pip install -e .

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 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).

# 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-convert	convert.py (package bubble.convert)
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-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
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 en --cover 7x10 --cover-provider ingram/hardcover --cover-version v2
bubble-batch all --no-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 true). Set false to skip optimize unless CLI passes --optimize-pdf… use --no-optimize-pdf to override per run.
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 can start 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.