RLHF Book - Build System

This directory contains the source files for building the RLHF Book in multiple formats (HTML, PDF, EPUB, DOCX).

Usage

From the repository root:

make          # Build all formats
make html     # Build HTML site
make pdf      # Build PDF (requires LaTeX)
make epub     # Build EPUB
make files    # Copy assets to build output

Known Conversion Issues

With the nested structure used for the website the section links between chapters in the PDF are broken. We are opting for this in favor of a better web experience, but best practice is to not put any links to rlhfbook.com within the Markdown files. Non-HTML versions will not be well suited to them.

Common Failures When Editing with Coding Agents

Valid UTF-8 Unicode punctuation, including curly quotes and em dashes, is supported by the book build. An error such as Cannot decode byte '\xe2': Data.Text.Encoding: Invalid UTF-8 stream indicates malformed or incorrectly encoded input, not the presence of valid Unicode punctuation.

Check a file's encoding with file -I book/chapters/filename.md or validate it with iconv -f UTF-8 -t UTF-8 book/chapters/filename.md >/dev/null. Keep source files as UTF-8; the PDF build normalizes TeX output where needed.

Installing

Please, check this page for more information.

Linux

NOTE: This is not fully tested.

Original build instructions:

sudo apt-get install pandoc

This template uses make to build the output files, so don't forget to install it too:

sudo apt-get install make

To export to PDF files, make sure to install the following packages:

sudo apt-get install texlive-fonts-recommended texlive-xetex

User-tested build instructions (see this issue):

On my PopOS 22.04 Linux system let me share how I got this book to build:

Install Pandoc 3.6.4 to avoid warning messages regarding pandoc-crossref

brew install pandoc-crossref is needed to get the build working right.

sudo apt install fonts-dejavu because my system repository had no ttf-dejavu package available

make clean to remove build artifacts

git pull in the project directory to update the local copy with the GitHub repository copy

Mac

brew install pandoc
brew install make
brew install pandoc-crossref

For the arXiv source bundle, also make sure the Python runner and LaTeX packages used by the PDF template are available:

brew install uv

Small TeX install:

brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install fvextra tcolorbox pdfcol

Fuller TeX install alternative:

brew install --cask mactex-no-gui

Build the arXiv-ready bundle from the repository root:

make -B latex

The generated source bundle is written to build/arxiv.zip.

The arXiv target copies only images referenced by the generated book.tex. If arXiv reports an oversized image, resize the source file in book/images below arXiv's pixel-count limit and rebuild with make -B latex.

Or, reuse the GitHub Actions workflow that auto-builds new versions on macOS.

Folder Structure

book/
├── chapters/     # Markdown source files (one per chapter)
├── images/       # Image assets referenced in chapters
├── assets/       # Brand assets (covers, logos)
├── templates/    # Pandoc templates for each output format
├── scripts/      # Build utilities
├── data/         # Library data (JSON)
└── preorder/     # Order redirect page

Setup

Edit the book/metadata.yml file to set configuration data:

---
title: My book title
author: Daniel Herzog
rights: MIT License
lang: en-US
tags: [pandoc, book, my-book, etc]
abstract: |
  Your summary.
mainfont: DejaVu Sans

# Filter preferences:
# - pandoc-crossref
linkReferences: true
---

You can find the list of all available keys on this page.

Creating Chapters

Creating a new chapter is as simple as creating a new Markdown file in the chapters/ folder; you'll end up with something like this:

chapters/01-introduction.md
chapters/02-installation.md
chapters/03-usage.md
chapters/04-references.md

Pandoc and Make will join them automatically ordered by name; that's why the numeric prefixes are being used.

For each chapter, specify at least one title:

# Introduction

This is the first paragraph of the introduction chapter.

## First

This is the first subsection.

## Second

This is the second subsection.

Each title (#) will represent a chapter, while each subtitle (##) will represent a chapter's section. You can use as many levels of sections as Markdown supports.

Manual control over page ordering

You may prefer to have manual control over page ordering instead of using numeric prefixes.

To do so, replace the CHAPTERS variable in the Makefile with your own order. For example:

CHAPTERS += $(addprefix ./book/chapters/,\
 01-introduction.md\
 02-installation.md\
 03-usage.md\
 04-references.md\
)

Links between chapters

Anchor links can be used to link chapters within the book:

// chapters/01-introduction.md
# Introduction

For more information, check the [Usage] chapter.

// chapters/02-installation.md
# Usage

...

If you want to rename the reference, use this syntax:

For more information, check [this](#usage) chapter.

Anchor names should be downcased, and spaces, colons, semicolons... should be replaced with hyphens. Instead of Chapter title: A new era, you have: #chapter-title-a-new-era.

Links between sections

It's the same as anchor links:

# Introduction

## First

For more information, check the [Second] section.

## Second

...

Or, with an alternative name:

For more information, check [this](#second) section.

Inserting Objects

Insert an image

Use Markdown syntax to insert an image with a caption:

![A cool seagull.](images/seagull.png)

Pandoc will automatically convert the image into a figure, using the title (the text between the brackets) as a caption.

If you want to resize the image, you may use this syntax, available since Pandoc 1.16:

![A cool seagull.](images/seagull.png){ width=50% height=50% }

Insert a table

Use a Markdown table, and use the Table: <Your table description> syntax to add a caption:

| Index | Name |
| ----- | ---- |
| 0     | AAA  |
| 1     | BBB  |
| ...   | ...  |

Table: This is an example table.

Insert an equation

Wrap a LaTeX math equation between $ delimiters for inline (tiny) formulas:

This, $\mu = \sum_{i=0}^{N} \frac{x_i}{N}$, the mean equation, ...

Pandoc renders equations as MathJax in HTML, MathML in EPUB, and native LaTeX in PDF.

If you want to center the equation instead of inlining it, use double $$ delimiters:

$$\mu = \sum_{i=0}^{N} \frac{x_i}{N}$$

Here's an online equation editor.

Cross references

Originally, this template used LaTeX labels for auto numbering on images, tables, equations or sections, like this:

Please, admire the gloriousness of Figure \ref{seagull_image}.

![A cool seagull.\label{seagull_image}](images/seagull.png)

However, these references only work when exporting to a LaTeX-based format (i.e. PDF, LaTeX).

In case you need cross-reference support in other formats, this template now supports cross-references using Pandoc filters. If you want to use them, use a valid plugin with its own syntax.

Using pandoc-crossref is highly recommended, but there are other alternatives which use a similar syntax, like pandoc-xnos.

First, enable the filter on the Makefile by updating the FILTER_ARGS variable with your new filter(s):

FILTER_ARGS = --filter pandoc-crossref

Then, you may use the filter cross references. For example, pandoc-crossref uses {#<type>:<id>} for definitions and @<type>:id for referencing. Some examples:

List of references:

- Check @fig:seagull.
- Check @tbl:table.
- Check @eq:equation.

List of elements to reference:

![A cool seagull](images/seagull.png){#fig:seagull}

$$ y = mx + b $$ {#eq:equation}

| Index | Name |
| ----- | ---- |
| 0     | AAA  |
| 1     | BBB  |
| ...   | ...  |

Table: This is an example table. {#tbl:table}

Check the desired filter settings and usage for more information (pandoc-crossref usage).

Content filters

If you need to modify the MD content before passing it to Pandoc, you may use CONTENT_FILTERS. By setting this Makefile variable, it will be passed to the Markdown content before passing it to Pandoc. For example, to replace all occurrences of @pagebreak with <div style="page-break-before: always;"></div> you may use a sed filter:

CONTENT_FILTERS = sed 's/@pagebreak/"<div style=\"page-break-before: always;\"><\/div>"/g'

To use multiple filters, you may include multiple pipes on the CONTENT_FILTERS variable:

CONTENT_FILTERS = \
  sed 's/@pagebreak/"<div style=\"page-break-before: always;\"><\/div>"/g' | \
  sed 's/@image/[Cool image](\/images\/image.png)/g'

Output

This template uses a Makefile to automate the build process. Instead of using the Pandoc CLI utility, we're going to use some make commands.

Export to PDF

Please note that PDF file generation requires some extra dependencies (~ 800 MB):

sudo apt-get install texlive-xetex ttf-dejavu

After installing the dependencies, use this command:

make pdf

The generated file will be placed in build/pdf.

Export to EPUB

Use this command:

make epub

The generated file will be placed in build/epub.

Export to HTML

Use this command:

make html

The generated file(s) will be placed in build/html.

Export to DOCX

Use this command:

make docx

The generated file(s) will be placed in build/docx.

Extra configuration

If you want to configure the output, you'll probably have to look at the Pandoc Manual for further information about PDF (LaTeX) generation, custom styles, etc., and modify the Makefile accordingly.

Templates

Output files are generated using Pandoc templates. All templates are located under the templates/ folder, and may be modified as you wish. Some basic format templates are already included in this repository, in case you need something to start with.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

RLHF Book - Build System

Usage

Known Conversion Issues

Common Failures When Editing with Coding Agents

Installing

Linux

Mac

Folder Structure

Setup

Creating Chapters

Manual control over page ordering

Links between chapters

Links between sections

Inserting Objects

Insert an image

Insert a table

Insert an equation

Cross references

Content filters

Output

Export to PDF

Export to EPUB

Export to HTML

Export to DOCX

Extra configuration

Templates

References