Build a PDF

It is possible to build a single PDF that contains all of your book’s content. This page describes a couple ways to do so.

Warning

PDF building is in active development, and may change or have bugs.

There are two approaches to building PDF files.

Build a PDF from your book HTML

It is possible to build a single PDF from your book’s HTML. This starts by converting all of your book’s content into a single HTML file, and then renders it as a PDF by emulating a browser from the command-line.

Installation

Your system will need to use pyppeteer to parse the generated HTML for conversion to PDF.

You can install it like so:

pip install pyppeteer

You may also need to install this bundle of packages below (on *nix systems):

gconf-service
libasound2
libatk1.0-0
libatk-bridge2.0-0
libc6
libcairo2
libcups2
libdbus-1-3
libexpat1
libfontconfig1
libgcc1
libgconf-2-4
libgdk-pixbuf2.0-0
libglib2.0-0
libgtk-3-0
libnspr4
libpango-1.0-0
libpangocairo-1.0-0
libstdc++6
libx11-6
libx11-xcb1
libxcb1
libxcomposite1
libxcursor1
libxdamage1
libxext6
libxfixes3
libxi6
libxrandr2
libxrender1
libxss1
libxtst6
ca-certificates
fonts-liberation
libappindicator1
libnss3
lsb-release
xdg-utils
wget

In addition, if you get errors about libraries that don’t exist, check out these install commands to see if that fixes it. We warned you it was an experimental feature :-)

Build

To build a single PDF from your book’s HTML, use the following command:

jupyter-book build mybookname/ --builder pdfhtml

or

jb build mybookname/ --builder pdfhtml

Warning

If you get a “MaxRetryError” and see mentions of SSL in the error message when building the PDF, this could be due to a bug in pyppeteer as it downloads Chromium for the first time. See this GitHub comment for a potential fix, and this Jupyter Book issue where we’re tracking the issue.

Control the look of PDF via HTML

Because you are using HTML as an intermediary for your book’s PDF, you can control the look and feel of the HTML via your own CSS rules. Most CSS changes that you make to your HTML website will also persist in the PDF version of that website. For information about how to define your own CSS rules, see Custom CSS or JavaScript.

To add CSS rules that only apply to the printed PDF, use the @media print CSS pattern to define print-specific rules. These will only be applied when the HTML is being printed, and will not show up in your non-PDF website.

For example, to hide the right table of contents at print time, you could add this rule:

@media print {
    .bd-toc {
        visibility: hidden;
    }
}

The right Table of Contents would be present in your live website, but hidden when someone printed a PDF of your website.

Build a PDF using LaTeX

You can also use LaTeX to build a PDF of your book. This process requires you to have tex setup on your system. Jupyter Book will construct a LaTeX file and then use the system latex to build that LaTeX file.

The LaTeX file that jupyter-book produces is not particularly easy to edit primarily because it contains sphinx and pygments markup to enable syntax highlighting for code cells etc. This is an area we would like to improve so that the LaTeX file is more human readable to enable customization.

See #1497

This section tries to recommend a few best-practices.

Note

We recommend using the texlive distribution

jupyter-book uses the sphinx-jupyterbook-latex package, which handles much of the customised LaTeX infrastructure. A full list of features can be found the sphinx-jupyterbook-latex features list.

Some of these features include:

1. This package enables building pdf files by providing support of the various structures that are defined in the _toc.yml. This also enables pdf files to be constructed in a way that is harmonised with the html output.

2. the masterdoc or root document for jupyter-book is treated as frontmatter in LaTeX

3. update fonts so that unicode characters can be used without breaking LaTeX builds (xelatex is used by default)

4. support for png and gif images using sphinx.ext.imgconverter

5. support for jupyter-book tags such as hide-cell

Note

This functionality is enabled by default, but if you need to turn off this package, you need add the following config to your _config.yml:

latex:
  use_jupyterbook_latex: false

Installation and Setup

For Debian-based Linux platforms it is recommended to install the following packages:

sudo apt-get install texlive-latex-extra \
                     texlive-fonts-extra \
                     texlive-xetex latexmk

Alternatively you can install the full TeX Live distribution.

For OSX you may want to use MacTeX which is a more user friendly approach. Alternatively you may also use TeX Live.

For Windows users, please install TeX Live.

Build

Book Style PDF

To build a PDF of your project using LaTeX, use the following command:

jupyter-book build mybookname/ --builder pdflatex

or

jb build mybookname/ --builder pdflatex

Note

If you would just like to generate the latex file you may use:

jb build mybookname/ --builder latex

Individual PDF Files

It is possible to build individual PDF files for each page of the project by enabling the --individualpages option when using the pdflatex builder.

jupyter-book build mybookname/ --builder pdflatex --individualpages

This option is only enabled for the pdflatex builder.

Warning

The current implementation of --individualpages does not make use of the improvements introduced by sphinx-jupyterbook-latex and uses the default latex writer included with Sphinx. We are currently working on making improvements to how --individualpages are constructed. You can track progress here

The individual PDF files will be available in the _build/latex build folder. These files will have the same name as the source file or, if nested in folders, will be named {folder}-{filename}.pdf in a flat structure.

Note

When specifying a single page using the build command, the --individualpages will automatically be set to True.

In the future we intend for this to produce latex documents more suitable to single pages (see issue #904).

Configuration

Updating the name of the book style PDF file

To update the name of your PDF file you can set the following in _config.yml

latex:
  latex_documents:
     targetname: book.tex

This will act as an automatic override when Sphinx builds the latex_documents. It is typically inferred by Sphinx but when using jupyter-book naming the file in the _config.yml generally makes it easier to find.

Choose a different LaTeX compiler

The current default is to use xelatex to build pdf files.

Warning

The --individualpages option currently uses pdflatex by default.

You may choose a different LaTeX engine such as pdflatex or lualatex. For example, to use pdflatex engine for LaTeX, add the following to your _config.yml:

latex:
  latex_engine: pdflatex

See also

The Sphinx documentation for available builders contains a full list of supported latex builders.

Customize LaTeX via Sphinx

The current focus of the EBP project has been to automate the process of building pdf files from myst:md sources and to ensure the resulting pdf files are synchronised (in structure) with the html output. We are actively looking at ways to enable more LaTeX configuration and customization.

The majority of customization offered is via Sphinx, the underlying build engine that powers jupyter-book.

Configuration via Sphinx LaTeX settings can be passed through using the config section of sphinx in the _config.yml file for your project.

For example, if you would like to set the latex_toplevel_sectioning option to use part instead of chapter you would use:

sphinx:
  config:
    latex_toplevel_sectioning: 'part'