# How to Generate EPUB from Markdown: Complete Build Pipeline for AI Agent Book > Generate EPUB from Markdown easily. Follow steps to install tools, run a build script, and automate your EPUB creation pipeline for your AI agent book project. - Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book) - Tags: how-to-guide - Published: 2026-08-22 --- **To generate EPUB from Markdown sources, install Pandoc and Poppler, run the [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh) script, and let the automated pipeline handle cover extraction, table-of-contents flattening, and optional EPUBCheck validation.** The bojieli/ai-agent-book repository maintains a sophisticated toolchain to generate EPUB from Markdown files across multiple languages. According to the project's [`EPUB.md`](https://github.com/bojieli/ai-agent-book/blob/main/EPUB.md) documentation and the [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh) driver script, the process combines Pandoc document conversion with custom post-processing utilities to handle everything from cover image extraction to right-to-left language support. ## Prerequisites: Installing Pandoc, Poppler, and EPUBCheck Before you can generate EPUB from Markdown sources, you must install the core conversion toolchain. The pipeline requires **Pandoc** as the conversion engine and **Poppler** (specifically `pdftoppm`) to extract the first-page PDF as the EPUB cover image. Optionally, install **EPUBCheck** to validate the generated files against the EPUB 3 specification. ```bash # Install required tools on Ubuntu/Debian sudo apt-get install pandoc poppler-utils # Optional: Install EPUBCheck for validation sudo apt-get install epubcheck ``` ## Running the Build Script The central entry point is [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh), which orchestrates the entire pipeline. Located in the repository root, this Bash script manages language detection, cover extraction, Pandoc invocation, and post-processing. ### Building All Supported Languages With no arguments, [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh) generates EPUB files for every language that has a fully validated PDF pipeline. As defined in [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh) at lines 34-38, this includes Chinese Simplified, Chinese Traditional, English, Spanish, Indonesian, Russian, Tamil, Vietnamese, Turkish, Korean, and Hungarian. ```bash # Build all validated languages ./build_epub.sh ``` ### Building Individual Languages To generate EPUB from Markdown for a specific language, pass its ISO 639-1 or ISO 639-2 language code as an argument. The script accepts codes such as `zh-CN`, `en`, `es`, or `ru`. ```bash # Build only the English edition ./build_epub.sh en ``` **Note:** Japanese (`ja`) and Arabic (`ar`) are explicitly excluded from the default "all" target because their PDF pipelines are still being validated, as documented in [`EPUB.md`](https://github.com/bojieli/ai-agent-book/blob/main/EPUB.md) at lines 13-22 and 31-33. To build these languages, you must invoke them explicitly: ```bash # Build Japanese or Arabic explicitly ./build_epub.sh ja ./build_epub.sh ar ``` ## Understanding the Post-Processing Pipeline After Pandoc converts the Markdown to EPUB format, the build script executes a multi-stage post-processing phase to ensure the output meets distribution standards. ### Cover Image Extraction with Poppler The script extracts the cover image from the first page of the corresponding PDF file using `pdftoppm` from Poppler. This extracted image becomes the EPUB cover, and the final `.epub` file is written adjacent to its source PDF in the file system. Generated EPUBs are automatically ignored by Git according to the repository's `.gitignore` configuration. ### TOC Flattening and RTL Language Support The script calls [`flatten_epub_toc.py`](https://github.com/bojieli/ai-agent-book/blob/main/flatten_epub_toc.py) to clean up the generated navigation structure. As implemented in lines 1-31 and 84-99 of [`flatten_epub_toc.py`](https://github.com/bojieli/ai-agent-book/blob/main/flatten_epub_toc.py), this Python utility performs several critical operations: - Removes automatic section numbers from the table of contents - Adds proper title and TOC entries to the NCX and navigation files - For right-to-left languages (such as Arabic), rewrites navigation files and sets the `page-progression-direction` attribute to `rtl` ### External Link Handling via Lua Filters To prevent EPUBCheck from flagging dangling resources, the pipeline uses a custom Pandoc Lua filter. The [`epub_external_links.lua`](https://github.com/bojieli/ai-agent-book/blob/main/epub_external_links.lua) script, referenced at lines 1-14, rewrites external links inside chapter files that point to sibling directories, converting them to absolute GitHub URLs before they reach the final EPUB output. ```bash # The script automatically runs these steps: # 1. pdftoppm (cover extraction) # 2. pandoc + epub_external_links.lua (conversion) # 3. flatten_epub_toc.py (TOC cleanup) # 4. epubcheck (optional validation) ``` ## Summary - **Tooling:** Generate EPUB from Markdown using Pandoc for conversion, Poppler for cover extraction, and EPUBCheck for validation. - **Entry Point:** Use [`./build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/./build_epub.sh) to build all validated languages, or pass a specific ISO code (e.g., `en`, `es`) for single-language builds. - **Exceptions:** Japanese and Arabic require explicit invocation and are excluded from the default build target due to ongoing PDF pipeline validation. - **Post-Processing:** The [`flatten_epub_toc.py`](https://github.com/bojieli/ai-agent-book/blob/main/flatten_epub_toc.py) script handles navigation cleanup and right-to-left language support, while [`epub_external_links.lua`](https://github.com/bojieli/ai-agent-book/blob/main/epub_external_links.lua) ensures external links point to valid absolute URLs. ## Frequently Asked Questions ### Why are Japanese and Arabic excluded from the default build target? According to [`EPUB.md`](https://github.com/bojieli/ai-agent-book/blob/main/EPUB.md) in the source repository, the PDF pipelines for Japanese and Arabic are still undergoing validation. While you can generate EPUB from Markdown for these languages by passing `ja` or `ar` explicitly to [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh), they are omitted from the "all" target to prevent incomplete builds in automated workflows. ### What does the [`flatten_epub_toc.py`](https://github.com/bojieli/ai-agent-book/blob/main/flatten_epub_toc.py) script do? This Python utility post-processes the raw EPUB output from Pandoc to remove automatically generated section numbers from the table of contents and add proper metadata entries. For right-to-left languages like Arabic, it also modifies the navigation files to set the correct `page-progression-direction` attribute, ensuring proper reading order in e-book readers. ### How does the build script handle external links? The pipeline passes the [`epub_external_links.lua`](https://github.com/bojieli/ai-agent-book/blob/main/epub_external_links.lua) filter to Pandoc during conversion. This Lua script rewrites relative links that point to sibling directories (which would be dangling in the standalone EPUB) into absolute GitHub URLs, ensuring EPUBCheck validation passes without resource errors. ### Is EPUB validation mandatory? No. If `epubcheck` is installed on your system, [`build_epub.sh`](https://github.com/bojieli/ai-agent-book/blob/main/build_epub.sh) automatically runs it against the generated files and outputs the results. If the tool is not found, the script simply prints a reminder message and exits successfully, leaving you with an unvalidated but fully functional EPUB file.