PDF Basics

Overview

Use the pdf format to create PDF output. For example:

---
title: "My document"
format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true
---

This example highlights a few of the options available for PDF output. This article covers these and other options in detail.

If you want to produce raw LaTeX output (a .tex file) rather than a PDF, all of the options documented here are still available (see the LaTeX Output section below for additional details).

Note

Note that while we will focus here exclusively on the use LaTeX to create PDFs, Pandoc also has support for creating PDFs using ConTeXt, roff ms, or HTML (via wkhtmltopdf). See the Pandoc documentation on Creating a PDF for additional details.

Prerequisites

In order to create PDFs you will need to install a recent distribution of TeX. We recommend the use of TinyTeX (which is based on TexLive), which you can install with the following command:

quarto tools install tinytex

See the article on PDF Engines for details on using other TeX distributions and PDF compilation engines.

Document Class

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

For PDF documents this results in the following Pandoc options set by default:

format:
  pdf:
    documentclass: scrartcl
    papersize: letter

You can set documentclass to the standard article, report or book classes, to the KOMA Script equivalents scrartcl, scrbook, and scrreprt, or to any other class made available by LaTeX packages you have installed.

See the Output Options section below for additional details on customizing LaTeX document options.

Table of Contents

Use the toc option to include an automatically generated table of contents in the output document. Use the toc-depth option to specify the number of section levels to include in the table of contents. The default is 3 (which means that level-1, 2, and 3 headings will be listed in the contents). For example:

toc: true
toc-depth: 2

You can customize the title used for the table of contents using the toc-title option:

toc-title: Contents

If you want to exclude a heading from the table of contents, add both the .unnumbered and .unlisted classes to it:

### More Options {.unnumbered .unlisted}

Section Numbering

Use the number-sections option to number section headings in the output document. For example:

number-sections: true

Use the number-depth option to specify the deepest level of heading to add numbers to (by default all headings are numbered). For example:

number-depth: 3

To exclude an individual heading from numbering, add the .unnumbered class to it:

### More Options {.unnumbered}

Syntax Highlighting

Pandoc will automatically highlight syntax in fenced code blocks that are marked with a language name.

You can specify the code highlighting style using highlight-style and specifying one of the supported themes. Supported themes include: arrow, pygments, tango, espresso, zenburn, kate, monochrome, breezedark, haddock, atom-one, ayu, breeze, dracula, github, gruvbox, monokai, nord, oblivion, printing, radical, solarized, and vim.

For example:

highlight-style: github

Highlighting themes can provide either a single highlighting definition or two definitions, one optimized for a light colored background and another optimized for a dark color background. When available, Quarto will automatically select the appropriate style based upon the code chunk background color’s darkness. You may may always opt to specify the full name (e.g. atom-one-dark) to bypass this automatic behavior.

By default, code is highlighted using the arrow theme, which is optimized for accessibility. Here are examples of the arrow light and dark themes:

Output Options

There are numerous options available for customizing PDF output, including:

  • Specifying document classes and their options

  • Including lists of figures and tables

  • Using the geometry and hyperref packages

  • Numerous options for customizing fonts and colors.

For example, here we use a few of these options:

---
title: "My Document"
format: 
  pdf: 
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    fontfamily: libertinus
    colorlinks: true
---

See the Pandoc documentation on metadata variables for LaTeX for documentation on all available options.

Citations

When creating PDFs, you can choose to use either the default Pandoc citation handling based on citeproc, or alternatively use natbib or BibLaTeX. This can be controlled using the cite-method option. For example:

format:
  pdf: 
    cite-method: biblatex

The default is to use citeproc (Pandoc’s built in citation processor).

See the main article on using Citations with Quarto for additional details on citation syntax, available bibliography formats, etc.

Options

When using natbib or biblatex you can specify the following additional options to affect how bibliographies are rendered:

Option Description
biblatexoptions List of options for biblatex
natbiboptions List of options for natbib
biblio-title Title for bibliography
biblio-style Style for bibliography

Raw LaTeX

When creating a PDF document, Pandoc allows the use of raw LaTeX directives intermixed with markdown. For example:

\begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}

Raw LaTeX commands will be preserved and passed unchanged to the LaTeX writer.

Warning

While it’s very convenient to use raw LaTeX, raw LaTeX is ignored when rendering to other formats like HTML and MS Word. If you plan on rendering to other formats then the example above would be better written using native markdown tables.

In some cases raw LaTeX will require additional LaTeX packages. The LaTeX Includes section below describes how to include \usepackage commands for these packages in your document.

LaTeX Includes

If you want to include additional content in your document from another file, you can use the include-in options:

Option Description
include-in-header Include contents of file, verbatim, into the LaTeX preamble.
include-before-body Include contents of file, verbatim, at the beginning of the document body (e.g. after the \begin{document} command).
include-after-body Include contents of file, verbatim, at the end of the document body (before the the \end{document}).

You can specify a single file for multiple files for each of these options. For example:

format:
  html:
    include-in-header:
      - packages.tex
      - macros.tex
    include-before-body: before.tex

There are also a set of options you can use for inline includes (i.e. specifying the included content right within YAML):

Option Description
header-includes Inline version of include-in-header
include-before Inline version of include-before-body
include-after Inline version include-after-body

For example:

format:
  pdf: 
    header-includes: |
      \usepackage{eplain}
      \usepackage{easy-todo}

Note the use of the | character on the line with header-includes to indicate that the value is a multi-line string.

If you don’t already have these packages installed locally, then Quarto will automatically install them during rendering of the document.

LaTeX Output

If you want Quarto to produce a LaTeX file (.tex) rather than a PDF (for example, if you want to do your own processing of the PDF) there are two ways to accomplish this:

  1. Use the latex format rather than the pdf format. For example:

    format:
      latex:
        documentclass: report
        classoption: [twocolumn, landscape]
        lof: true
        lot: true

    Note that all of the PDF format options documented above will also work for the latex format.

  2. Use the pdf format along with the keep-tex option. For example:

    format:
      pdf:
        documentclass: report
        keep-tex: true

    This technique will produce a PDF file for preview, but will also create a .tex file alongside it that you can do subsequent processing on.