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

    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

Cover Images

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

  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:

     cover-image: cover.png
     cover-image: cover-highres.png

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:

  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:

  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 with the keep-tex option:

    keep-tex: true

The complete LaTeX source code of your book will be output into the main book source directory (e.g. to “my-book.tex”). This LaTeX can be compiled without Quarto, so is suitable for submitting to an external publisher.

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:

    theme: cosmo

To further customize a theme add a custom theme file:

    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:

    css: styles.css

EPUB Styles

You can also use CSS to customize EPUB output:

    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:

    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:

MS Word Styles

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

    reference-doc: custom-reference.docx

To create a new reference doc based on the Pandoc default, execute the following command:

quarto pandoc -o custom-reference.docx --print-default-data-file reference.docx

Then, open custom-reference.docx in MS Word and modify styles as you wish:

A screen shot of a Microsoft Word document. The Styles pane is open on the right hand side of the document.

When you move the cursor to a specific element in the document, an item in the styles list will be highlighted. If you want to modify the style of any type of element, you can click the drop-down menu on the highlighted item, and you will see a dialog box like this:

The 'Modify Style' menu from Microsoft Word. The color selection box is open, displaying the color palette.

After you finish modifying the styles, you can save the document and use it as the template for future Word documents.