Customizing Book Output

This article covers customizing the output of book projects, including how to tailor the styles and appearance of books in each supported output format.

Format Options

If you want to specify rendering options (including format-specific options), you do it within the _quarto.yml project file rather than within the individual markdown documents. This is because when rendering a book all of the chapters are combined together into a single document (with a single set of format options).

Here’s an example configuration:

highlight-style: pygments

format:
  html:
    theme: cosmo
    code-copy: true
  pdf: default
    
bibliography: references.bib
csl: citestyle.csl

Note that in the above configuration the highlight-style option applies to all formats whereas the html options apply to only HTML output. The bibliography related options naturally also apply to all formats.

Reader Tools

Website Tools

HTML books are at their core Quarto Websites with some special navigational behavior built in. This means that all of the features described for enhancing websites are also available for books, including:

One important thing to note about using website tools is that while these tools are added to websites within the website key, in a book you should include the same options in the book key. For example, in a website you would include a favicon and twitter card as follows:

website:
  favicon: logo.png
  twitter-card: true
  site-url: https://example.com

In a book you’d use the book key instead:

book:
  favicon: logo.png
  twitter-card: true
  site-url: https://example.com

Cover Images

You can provide a cover image for EPUB and/or HTML formats using the cover-image option. For example:

book:
  cover-image: cover.png

You can also do this on a per-format basis (if for example you want to provide a higher resolution image for EPUB and a lower resolution image for HTML to reduce download time). For example:

format:
   html: 
     cover-image: cover.png
   epub:
     cover-image: cover-highres.png

You can specify HTML alt-text for book cover images using the cover-image-alt option:

book:
  cover-image: cover.png
  cover-image-alt: |
    Alternative text describing the book cover

Output Path

By default, book output is written to the _book directory of your project. You can change this via the output-dir project option. For example:

project:
  type: book
  output-dir: docs

Single file outputs like PDF, EPUB, etc. are also written to the output-dir. Their file name is derived from the book title. You can change this via the output-file option:

book:
  title: "My Book"
  output-file: "my-book"

Note that the output-file should not have a file extension (that will be provided automatically as appropriate for each format).

LaTeX Output

In some cases you’ll want to do customization of the LaTeX output before creating the final printed manuscript (e.g. to affect how text flows between pages or within and around figures). The best way to approach this is to develop your book all the way to completion, then render to the latex format

Terminal
quarto render --to latex

The complete LaTeX source code of your book will be output into the _book/book-latex directory.

At this point you should probably make a copy or git branch of the _book directory to perform your final LaTeX modifications within (since the modifications you make to LaTeX will not be preserved in your markdown source, and will therefore be overwritten the next time you render).

HTML Styles

HTML output can be customized either by adding (or enhancing) a custom theme, or by providing an ordinary CSS file. Use the theme option to specify a theme:

format:
  html:
    theme: cosmo

To further customize a theme add a custom theme file:

format:
  html:
    theme: [cosmo, theme.scss]

You can learn more about creating theme files in the documentation on HTML Themes.

You can also just use plain CSS. For example:

format:
  html:
    css: styles.css

EPUB Styles

You can also use CSS to customize EPUB output:

format:
  epub:
    css: epub-styles.css
    epub-cover-image: epub-cover.png

Note that we also specify a cover image. To learn more about other EPUB options, see the Pandoc documentation on EPUBs.

PDF Styles

You can include additional LaTeX directives in the preamble of your book using the include-in-header option. You can also add documentclass and other options (see the Pandoc documentation on LaTeX options for additional details). For example:

format:
  pdf: 
    documentclass: scrbook
    include-in-header: preamble.tex
    fontfamily: libertinus

Quarto uses the KOMA Script scrreprt document class by default for PDF books. KOMA-Script classes are drop-in replacements for the standard classes with an emphasis on typography and versatility.

You can switch to KOMA scrbook as demonstrated above, or to the standard LaTeX book and report classes. You can find a summary of the differences between book and report here: https://tex.stackexchange.com/questions/36988

MS Word Styles

You can customize MS Word output by creating a new reference doc, and then applying it to your book as follows:

format:
  docx:
    reference-doc: custom-reference.docx

Learn more about creating and customizing a reference document in the documentation on Word templates.