A reusable Pandoc + XeLaTeX build system for creating professional technical books in PDF, HTML, and EPUB formats.
- Multiple Output Formats: PDF (print-ready), HTML (web), EPUB (e-readers)
- PDF/X-1a Compliance: Professional print-ready output
- Atkinson Hyperlegible Font: Excellent readability (~10MB fonts included)
- Syntax Highlighting: Beautiful code blocks with language-specific styling
- Custom Callout System: Note, warning, caution, info, and example boxes
- Flexible Configuration: YAML-based metadata and settings
- Image Processing: Automatic optimization and DPI handling
- Link Processing: Smart repository and cross-reference handling
-
Pandoc 3.0+
brew install pandoc
-
XeLaTeX (for PDF generation)
brew install --cask mactex
-
Node.js 16+
brew install node
# Clone the repository
git clone https://github.com/satkinson/book-builder.git
cd book-builder
# Install dependencies
npm install
# Verify setup
npm run pandoc:testcd your-book-project
git submodule add https://github.com/satkinson/book-builder.git book-builder
git submodule update --init --recursive
cd book-builder
npm install# Build the sample book
node scripts/build-book.js examples/sample-book --target pdfOutput will be in examples/sample-book/build/.
# Copy the example as a template
cp -r examples/sample-book my-book
cd my-book
# Edit metadata.yaml with your book information
# Add your chapter files (chapter1.md, chapter2.md, etc.)
# Build your book
node ../scripts/build-book.js . --target pdf# Build specific format
node scripts/build-book.js /path/to/book-content --target pdf
node scripts/build-book.js /path/to/book-content --target web
node scripts/build-book.js /path/to/book-content --target epub
# Build all formats
node scripts/build-book.js /path/to/book-content --target all# From your book directory
node book-builder/scripts/build-book.js . --target pdfbook-builder/
├── config/
│ └── pandoc-defaults.yaml # Pandoc settings
├── scripts/
│ ├── build-book.js # Main build script
│ ├── validate-links.js # Link validation
│ └── process-images.js # Image processing
├── templates/
│ ├── book-digital.latex # PDF template (digital)
│ ├── book-print.latex # PDF template (print)
│ └── filters/ # Pandoc Lua filters
│ ├── callout-filter.lua # Process callouts
│ └── link-filter.lua # Process repository links
├── fonts/ # Atkinson Hyperlegible (~10MB)
├── styles/ # CSS and styling
├── examples/
│ └── sample-book/ # Example book project
└── package.json # Dependencies and scripts
my-book/
├── metadata.yaml # Book metadata (required)
├── chapter1.md # Your chapters
├── chapter2.md
├── images/ # Book images (optional)
├── build/ # Generated output (created automatically)
└── book-builder/ # Submodule (if using)
Create a metadata.yaml file in your book directory:
---
title: "Your Book Title"
subtitle: "Optional Subtitle"
author: "Your Name"
date: "2024"
version: "1.0"
edition: "First Edition"
isbn: ""
isbn13: ""
publisher: "Your Publisher"
abstract: |
A brief description of your book.
---Create special callout boxes:
::: note
This is a note callout with blue background.
:::
::: warning
This is a warning callout with orange background.
:::
::: caution
This is a caution callout with red background.
:::
::: info
This is an info callout with green background.
:::
::: example
This is an example callout with purple background.
:::\```javascript
function hello(name) {
console.log(`Hello, ${name}!`);
}
\```See [Chapter 2](#chapter-2) for more details.
Check out the [documentation](https://example.com).# From book-builder directory
npm run build:pdf # Build PDF
npm run build:web # Build HTML
npm run build:epub # Build EPUB
npm run build:all # Build all formats
npm run clean # Clean build outputs
npm run pandoc:test # Verify Pandoc and XeLaTeX installed- PDF/X-1a compliant
- 300 DPI images
- Atkinson Hyperlegible font
- Professional typography
- Print-optimized
- Responsive design
- Syntax highlighting
- Interactive navigation
- Web-optimized
- E-reader compatible
- Reflowable text
- Embedded fonts
- Chapter navigation
The Atkinson Hyperlegible font family is included (~10MB) in the fonts/ directory. To use different fonts:
- Add font files to
fonts/directory - Update
templates/book-digital.latexandtemplates/book-print.latex - Update font references in the templates
- PDF Template:
templates/book-digital.latex(digital) ortemplates/book-print.latex(print) - CSS:
styles/book.css(HTML output) - Filters:
templates/filters/(custom Pandoc processing)
Edit templates/filters/callout-filter.lua to customize callout appearance and behavior.
"Pandoc not found"
brew install pandoc
pandoc --version # Should be 3.0+"XeLaTeX not found"
brew install --cask mactex
# Restart terminal
xelatex --version"Font not found"
- Fonts are included in the
fonts/directory - Verify fonts exist:
ls fonts/
Build fails with errors
# Run with verbose output
node scripts/build-book.js /path/to/book --target pdf --verboseSee examples/sample-book/ for a complete working example.
MIT License - see LICENSE file for details.
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
- Built with Pandoc
- Uses Atkinson Hyperlegible font from the Braille Institute
- LaTeX typesetting via XeLaTeX
For issues, questions, or contributions:
- GitHub Issues: https://github.com/satkinson/book-builder/issues
- Documentation: https://github.com/satkinson/book-builder
Created by Steve Atkinson • Originally developed for "The Constellize Method" book