# How to Build the Curriculum Book Series Using `scripts/build_book.py`

> Learn to build the curriculum book series using scripts/build_book.py in the ai-engineering-from-scratch repository. Compile markdown to EPUB and PDF effortlessly.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-09-01

---

**The [`scripts/build_book.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_book.py) script in the `rohitg00/ai-engineering-from-scratch` repository orchestrates the compilation of markdown lessons into professional EPUB and PDF books by processing volume definitions from [`book/volumes.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/book/volumes.json) and invoking Pandoc.**

This guide explains how to build the curriculum book series using [`scripts/build_book.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_book.py), covering the complete pipeline from lesson discovery to final artifact generation. The script automates the assembly of phase-based lesson content, handles multilingual translations, and produces both digital and print-ready formats.

## Prerequisites and Environment Setup

Before executing the build script, ensure your environment meets the tooling requirements. The script depends on external binaries for document conversion.

**Pandoc** is mandatory for all build operations. The script calls Pandoc directly to convert assembled markdown into EPUB format at [`scripts/build_book.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_book.py) lines 129–138.

For **PDF generation**, you must install a LaTeX distribution providing `xelatex`, as the script uses XeLaTeX engines to render PDFs with Unicode and custom font support (lines 147–176). The script also requires `fc-list` (fontconfig) for the `pick_font()` function to detect system-installed fonts.

Optionally, install the **Mermaid CLI (`mmdc`)** to render ` ```mermaid` ` blocks into embedded SVG diagrams rather than placeholder boxes.

## Understanding the Build Pipeline

The build process consists of six distinct phases orchestrated by the main execution block. Each phase is implemented as a specific function in `scripts/build_book.py`.

1. **Argument Parsing** – Processes `--volume`, `--pdf`, `--assemble-only`, and `--lang` flags to set the `BOOK_LANG` environment and target volume (lines 19–28).
2. **Phase Validation** – The `check_phases()` function verifies that every phase listed in a volume definition exists in the filesystem and contains valid lesson content (lines 107–116).
3. **Markdown Assembly** – The `assemble(vol)` function walks each phase, reads lesson files (prioritizing `i18n/<lang>/` translations over `docs/en.md`), rewrites asset paths, and concatenates content into a single markdown file (core loop at lines 93–100).
4. **Metadata Generation** – The `metadata(vol)` function writes a YAML front-matter file containing the book title, author, and series information for Pandoc consumption.
5. **Rendering** – The `render(vol, md, chapters, pdf)` function executes Pandoc commands to generate EPUBs and optionally PDFs using the `book/titlepage.tex` LaTeX template.
6. **Output** – Final artifacts are written to `dist/book/` with naming convention `aiefs-vol<NUM>-<slug>.epub` and `.pdf`.

## Configuration and Volume Definitions

The script relies on `book/volumes.json` to determine which phases comprise each volume. This JSON file maps volume slugs to their respective lesson phases.

```json
{
  "volumes": [
    {
      "slug": "fundamentals",
      "number": 1,
      "title": "AI Engineering Fundamentals",
      "phases": ["phase-01-intro", "phase-02-basics"]
    }
  ]
}

```

The script reads this configuration at startup via `CONFIG = json.loads((ROOT / "book" / "volumes.json").read_text(...))`. The `lesson_dirs(phase)` function then discovers individual lessons within each phase directory using the `LESSON_DIR_RE` regex pattern, ensuring only directories containing `docs/en.md` (or translated equivalents) are included.

## Assembling Lesson Content

During the assembly phase, the script performs several content transformations to ensure offline usability:

- **Asset Path Rewriting** – Updates image references to point to the repository’s `assets` folder.
- **Interactive Enhancement Injection** – Replaces special fenced blocks like ` ```figure` ` and ` ```mermaid` ` with "continue-online" boxes that link readers to the live web edition at `SITE`.
- **Mermaid Rendering** – If `mmdc` is available, Mermaid diagrams are pre-rendered to SVG and embedded directly; otherwise, placeholder boxes are inserted.

The `assemble()` function handles language selection by checking for the existence of `i18n/<BOOK_LANG>/phases/<phase>/<lesson>/docs/<lang>.md` before falling back to the English source. This allows the script to build localized versions of the curriculum when translations exist.

## Command-Line Usage

Build operations are controlled via command-line arguments processed by `argparse` in the script’s main block.

**Build all volumes (EPUB only):**

```bash
python3 scripts/build_book.py

```

**Build a specific volume by slug:**

```bash
python3 scripts/build_book.py --volume fundamentals

```

**Build with PDF output (left-to-right languages only):**

```bash
python3 scripts/build_book.py --volume fundamentals --pdf

```

**Assemble markdown without rendering:**

```bash
python3 scripts/build_book.py --assemble-only

```

**Build in a specific language:**

```bash
python3 scripts/build_book.py --lang es --volume fundamentals

```

The `--lang` flag sets the `BOOK_LANG` variable, directing the script to prefer content from `i18n/<lang>/` paths when available.

## Output Artifacts and File Structure

After successful execution, the script produces files in three locations:

- **Assembled Markdown:** `book/_build/<volume>.md` – The concatenated, transformed markdown source used as Pandoc input.
- **EPUB Files:** `dist/book/aiefs-vol<NUM>-<slug>.epub` – The primary e-book format.
- **PDF Files:** `dist/book/aiefs-vol<NUM>-<slug>.pdf` – Generated only when `--pdf` is specified and the language supports left-to-right rendering.

The script creates the `dist/book/` directory automatically (lines 38–45) if it does not exist.

## PDF Generation and Font Handling

When `--pdf` is requested, the script performs additional font detection via `pick_font()`. This function queries system fonts using `fc-list` to select appropriate serif, monospaced, or CJK typefaces based on the target language. The selected fonts are passed to the `xelatex` command via the `book/titlepage.tex` template, which handles the title page layout with edition numbers and chapter counts.

PDF generation is explicitly skipped for right-to-left languages or when `xelatex` is unavailable, ensuring the build process fails gracefully.

## Summary

- **[`scripts/build_book.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/build_book.py)** automates the entire book-building pipeline for the AI Engineering from Scratch curriculum.
- Configuration is defined in **[`book/volumes.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/book/volumes.json)**, mapping volumes to specific lesson phases.
- The script supports **multilingual builds** via the `--lang` flag and `i18n/` directory structure.
- **Pandoc** is required for EPUB generation; **XeLaTeX** and system fonts are required for PDF output.
- Use **`--assemble-only`** to debug markdown content before final rendering.
- Output files are written to **`dist/book/`** with standardized naming conventions.

## Frequently Asked Questions

### What dependencies are required to run the build script?

The script requires **Pandoc** installed and available in your system PATH to generate EPUB files. For PDF generation, you need a LaTeX distribution providing the `xelatex` binary, along with `fontconfig` (for the `fc-list` command) to enable font detection. The optional `mmdc` CLI enables rendering of Mermaid diagrams to SVG.

### How do I build only a specific volume instead of the entire series?

Pass the `--volume` argument followed by the volume slug as defined in [`book/volumes.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/book/volumes.json). For example, `python3 scripts/build_book.py --volume fundamentals` processes only the phases associated with that volume, significantly reducing build time.

### Why does PDF generation fail or get skipped for my language?

PDF generation is restricted to left-to-right languages. The script checks the language direction and will skip PDF rendering if the script detects a right-to-left script. Additionally, PDF generation requires `xelatex` and appropriate system fonts; if these are missing, the script will build the EPUB but skip the PDF step.

### Where can I find the assembled markdown source before Pandoc converts it?

The concatenated markdown file is written to `book/_build/<volume>.md` during the assembly phase. Use the `--assemble-only` flag to generate this file without invoking Pandoc, allowing you to inspect how lesson content, image paths, and special blocks are transformed before final rendering.