Portable Document Format (PDF) is a file format developed by Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. To learn more about PDF see https://en.wikipedia.org/wiki/PDF.
See the PDF format user guide for more details on creating PDF output with Quarto.
format: pdf

Title & Author







title
Document title


subtitle
Identifies the subtitle of the document.


date
Document date


author
Author or authors of the document


abstract
Summary of document


thanks
The contents of an acknowledgments footnote after the document title.


order
Order for document when included in a website automatic sidebar menu.





Format Options



pdf-engine
Use the specified engine when producing PDF output. If the engine is not in your PATH, the full path of the engine may be specified here. If this option is not specified, Quarto uses the following defaults depending on the output format in use:

latex: xelatex (other options: pdflatex, lualatex, tectonic, latexmk)
context: context
html: wkhtmltopdf (other options: prince, weasyprint; see print-css.rocks for a good introduction to PDF generation from HTML/CSS.)
ms: pdfroff



pdf-engine-opt
Use the given string as a command-line argument to the pdf-engine. For example, to use a persistent directory foo for latexmk’s auxiliary files, use pdf-engine-opt: -outdir=foo. Note that no check for duplicate options is done.


quarto-required
A semver version range describing the supported quarto versions for this document or project.
Examples:

>= 1.1.0: Require at least quarto version 1.1
1.*: Require any quarto versions whose major version number is 1






Table of Contents







toc
Include an automatically generated table of contents (or, in the case of latex, context, docx, odt, opendocument, rst, or ms, an instruction to create one) in the output document. This option has no effect if standalone is false.
Note that if you are producing a PDF via ms, the table of contents will appear at the beginning of the document, before the title. If you would prefer it to be at the end of the document, use the option pdf-engine-opt: --no-toc-relocation.


toc-depth
Specify the number of section levels to include in the table of contents. The default is 3


toc-title
The title used for the table of contents.


lof
Print a list of figures in the document.


lot
Print a list of tables in the document.





Numbering







number-sections
Number section headings rendered output. By default, sections are not numbered. Sections with class .unnumbered will never be numbered, even if number-sections is specified.


number-depth
By default, all headings in your document create a numbered section. You customize numbering depth using the number-depth option.
For example, to only number sections immediately below the chapter level, use this:
number-depth: 1


number-offset
Offset for section headings in output (offsets are 0 by default) The first number is added to the section number for top-level headings, the second for second-level headings, and so on. So, for example, if you want the first top-level heading in your document to be numbered “6”, specify number-offset: 5. If your document starts with a level-2 heading which you want to be numbered “1.5”, specify number-offset: [1,4]. Implies number-sections


shift-heading-level-by
Shift heading levels by a positive or negative integer. For example, with shift-heading-level-by: -1, level 2 headings become level 1 headings, and level 3 headings become level 2 headings. Headings cannot have a level less than 1, so a heading that would be shifted below level 1 becomes a regular paragraph. Exception: with a shift of -N, a level-N heading at the beginning of the document replaces the metadata title.


top-level-division
Treat top-level headings as the given division type (default, section, chapter, or part). The hierarchy order is part, chapter, then section; all headings are shifted such that the top-level heading becomes the specified type.
The default behavior is to determine the best division type via heuristics: unless other conditions apply, section is chosen. When the documentclass variable is set to report, book, or memoir (unless the article option is specified), chapter is implied as the setting for this option. If beamer is the output format, specifying either chapter or part will cause top-level headings to become \part{..}, while second-level headings remain as their default type.





Fonts



mainfont
For HTML output, sets the CSS font-family on the HTML element.
For LaTeX output, the main font family for use with xelatex or lualatex. Takes the name of any system font, using the fontspec package.
For ConTeXt output, the main font family. Use the name of any system font. See ConTeXt Fonts for more information.


monofont
For HTML output, sets the CSS font-family property on code elements.
For PowerPoint output, sets the font used for code.
For LaTeX output, the monospace font family for use with xelatex or lualatex: take the name of any system font, using the fontspec package.
For ConTeXt output, the monspace font family. Use the name of any system font. See ConTeXt Fonts for more information.


fontsize
For HTML output, sets the base CSS font-size property.
For LaTeX and ConTeXt output, sets the font size for the document body text.


fontenc
Allows font encoding to be specified through fontenc package.
See LaTeX Font Encodings Guide for addition information on font encoding.


fontfamily
Font package to use when compiling a PDf with the pdflatex pdf-engine.
See The LaTeX Font Catalogue for a summary of font options available.
For groff (ms) files, the font family for example, T or P.


fontfamilyoptions
Options for the package used as fontfamily.
For example, to use the Libertine font with proportional lowercase (old-style) figures through the libertinus package:
fontfamily: libertinus
fontfamilyoptions:
  - osf
  - p


sansfont
The sans serif font family for use with xelatex or lualatex. Takes the name of any system font, using the fontspec package.


mathfont
The math font family for use with xelatex or lualatex. Takes the name of any system font, using the fontspec package.


CJKmainfont
The CJK main font family for use with xelatex or lualatex using the xecjk package.


mainfontoptions
The main font options for use with xelatex or lualatex allowing any options available through fontspec.
For example, to use the TeX Gyre version of Palatino with lowercase figures:
mainfont: TeX Gyre Pagella
mainfontoptions:
  - Numbers=Lowercase
  - Numbers=Proportional    


sansfontoptions
The sans serif font options for use with xelatex or lualatex allowing any options available through fontspec.


monofontoptions
The monospace font options for use with xelatex or lualatex allowing any options available through fontspec.


mathfontoptions
The math font options for use with xelatex or lualatex allowing any options available through fontspec.


CJKoptions
The CJK font options for use with xelatex or lualatex allowing any options available through fontspec.


microtypeoptions
Options to pass to the microtype package.


linestretch
For HTML output sets the CSS line-height property on the html element, which is preferred to be unitless.
For LaTeX output, adjusts line spacing using the setspace package, e.g. 1.25, 1.5.





Colors



linkcolor
For HTML output, sets the CSS color property on all links.
For LaTeX output, The color used for internal links using color options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists.
For ConTeXt output, sets the color for both external links and links within the document.


filecolor
The color used for external links using color options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists.


citecolor
The color used for citation links using color options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists.


urlcolor
The color used for linked URLs using color options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists.


toccolor
The color used for links in the Table of Contents using color options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists.


colorlinks
Add color to link text, automatically enabled if any of linkcolor, filecolor, citecolor, urlcolor, or toccolor are set.





Layout



cap-location
Where to place figure and table captions (top, bottom, or margin)


fig-cap-location
Where to place figure captions (top, bottom, or margin)


tbl-cap-location
Where to place table captions (top, bottom, or margin)


documentclass
The document class.


classoption
For LaTeX/PDF output, the options set for the document class.
For HTML output using KaTeX, you can render display math equations flush left using classoption: fleqn


pagestyle
Control the \pagestyle{} for the document.


papersize
The paper size for the document.


grid
Properties of the grid system used to layout Quarto HTML pages.


margin-left
For HTML output, sets the margin-left property on the Body element.
For LaTeX output, sets the left margin if geometry is not used (otherwise geometry overrides this value)
For ConTeXt output, sets the left margin if layout is not used, otherwise layout overrides these.
For wkhtmltopdf sets the left page margin.


margin-right
For HTML output, sets the margin-right property on the Body element.
For LaTeX output, sets the right margin if geometry is not used (otherwise geometry overrides this value)
For ConTeXt output, sets the right margin if layout is not used, otherwise layout overrides these.
For wkhtmltopdf sets the right page margin.


margin-top
For HTML output, sets the margin-top property on the Body element.
For LaTeX output, sets the top margin if geometry is not used (otherwise geometry overrides this value)
For ConTeXt output, sets the top margin if layout is not used, otherwise layout overrides these.
For wkhtmltopdf sets the top page margin.


margin-bottom
For HTML output, sets the margin-bottom property on the Body element.
For LaTeX output, sets the bottom margin if geometry is not used (otherwise geometry overrides this value)
For ConTeXt output, sets the bottom margin if layout is not used, otherwise layout overrides these.
For wkhtmltopdf sets the bottom page margin.


geometry
Options for the geometry package. For example:
geometry:
  - top=30mm
  - left=20mm
  - heightrounded


hyperrefoptions
Options for the hyperref package. For example:
hyperrefoptions:
  - linktoc=all
  - pdfwindowui
  - pdfpagemode=FullScreen      
To customize link colors, please see the Quarto PDF reference.


indent
Whether to use document class settings for indentation. If the document class settings are not used, the default LaTeX template removes indentation and adds space between paragraphs
For groff (ms) documents, the paragraph indent, for example, 2m.


block-headings
Make \paragraph and \subparagraph (fourth- and fifth-level headings, or fifth- and sixth-level with book classes) free-standing rather than run-in; requires further formatting to distinguish from \subsubsection (third- or fourth-level headings). Instead of using this option, KOMA-Script can adjust headings more extensively:
header-includes: |
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\itshape]{paragraph}
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\scshape,
    indent=0pt]{subparagraph}





Code



code-line-numbers
Include line numbers in code block output (true or false).
For revealjs output only, you can also specify a string to highlight specific lines (and/or animate between sets of highlighted lines).

Sets of lines are denoted with commas:

3,4,5
1,10,12

Ranges can be denoted with dashes and combined with commas:

1-3,5
5-10,12,14

Finally, animation steps are separated by |:

1-3|1-3,5 first shows 1-3, then 1-3,5
|5|5-10,12 first shows no numbering, then 5, then lines 5-10 and 12




code-annotations
The style to use when displaying code annotations. Set this value to false to hide code annotations.


code-block-border-left
Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is enabled as well as the color of the border.=


code-block-bg
Specifies to apply a background color on code blocks. Provide a hex color to specify that the background color is enabled as well as the color of the background.


highlight-style
Specifies the coloring style to be used in highlighted source code.
Instead of a STYLE name, a JSON file with extension .theme may be supplied. This will be parsed as a KDE syntax highlighting theme and (if valid) used as the highlighting style.


syntax-definitions
KDE language syntax definition files (XML)


listings
Use the listings package for LaTeX code blocks. The package does not support multi-byte encoding for source code. To handle UTF-8 you would need to use a custom template. This issue is fully documented here: Encoding issue with the listings package


indented-code-classes
Specify classes to use for all indented code blocks





Execution
Execution options should be specified within the execute key. For example:
execute:
  echo: false
  warning: false



eval
Evaluate code cells (if false just echos the code into output).

true (default): evaluate code cell
false: don’t evaluate code cell
[...]: A list of positive or negative line numbers to selectively include or exclude lines (explicit inclusion/excusion of lines is available only when using the knitr engine)



echo
Include cell source code in rendered output.

true (default): include source code in output
false: do not include source code in output
fenced: in addition to echoing, include the cell delimiter as part of the output.
[...]: A list of positive or negative line numbers to selectively include or exclude lines (explicit inclusion/excusion of lines is available only when using the knitr engine)



output
Include the results of executing the code in the output. Possible values:

true: Include results.
false: Do not include results.
asis: Treat output as raw markdown with no enclosing containers.



warning
Include warnings in rendered output.


error
Include errors in the output (note that this implies that errors executing code will not halt processing of the document).


include
Catch all for preventing any output (code or results) from being included in output.


cache
Cache results of computations (using the knitr cache for R documents, and Jupyter Cache for Jupyter documents).
Note that cache invalidation is triggered by changes in chunk source code (or other cache attributes you’ve defined).

true: Cache results
false: Do not cache results
refresh: Force a refresh of the cache even if has not been otherwise invalidated.



freeze
Control the re-use of previous computational output when rendering.

true: Never recompute previously generated computational output during a global project render
false (default): Recompute previously generated computational output
auto: Re-compute previously generated computational output only in case their source file changes






Figures







fig-align
Figure horizontal alignment (default, left, right, or center)


fig-env
LaTeX environment for figure output


fig-pos
LaTeX figure position arrangement to be used in \begin{figure}[].
Computational figure output that is accompanied by the code that produced it is given a default value of fig-pos="H" (so that the code and figure are not inordinately separated).
If fig-pos is false, then we don’t use any figure position specifier, which is sometimes necessary with custom figure environments (such as sidewaysfigure).


fig-cap-location
Where to place figure captions (top, bottom, or margin)


fig-width
Default width for figures generated by Matplotlib or R graphics.
Note that with the Jupyter engine, this option has no effect when provided at the cell level; it can only be provided with document or project metadata.


fig-height
Default height for figures generated by Matplotlib or R graphics.
Note that with the Jupyter engine, this option has no effect when provided at the cell level; it can only be provided with document or project metadata.


fig-format
Default format for figures generated by Matplotlib or R graphics (retina, png, jpeg, svg, or pdf)


fig-dpi
Default DPI for figures generated by Matplotlib or R graphics.
Note that with the Jupyter engine, this option has no effect when provided at the cell level; it can only be provided with document or project metadata.


fig-asp
The aspect ratio of the plot, i.e., the ratio of height/width. When fig-asp is specified, the height of a plot (the option fig-height) is calculated from fig-width * fig-asp.
The fig-asp option is only available within the knitr engine.





Tables







tbl-colwidths
Apply explicit table column widths for markdown grid tables and pipe tables that are more than columns characters wide (72 by default).
Some formats (e.g. HTML) do an excellent job automatically sizing table columns and so don’t benefit much from column width specifications. Other formats (e.g. LaTeX) require table column sizes in order to correctly flow longer cell content (this is a major reason why tables > 72 columns wide are assigned explicit widths by Pandoc).
This can be specified as:

auto: Apply markdown table column widths except when there is a hyperlink in the table (which tends to throw off automatic calculation of column widths based on the markdown text width of cells). (auto is the default for HTML output formats)
true: Always apply markdown table widths (true is the default for all non-HTML formats)
false: Never apply markdown table widths.
An array of numbers (e.g. [40, 30, 30]): Array of explicit width percentages.



tbl-cap-location
Where to place table captions (top, bottom, or margin)


df-print
Method used to print tables in Knitr engine documents:

default: Use the default S3 method for the data frame.
kable: Markdown table using the knitr::kable() function.
tibble: Plain text table using the tibble package.
paged: HTML table with paging for row and column overflow.

The default printing method is kable.





References







bibliography
Document bibliography (BibTeX or CSL). May be a single file or a list of files


csl
Citation Style Language file to use for formatting references.


cite-method
Method used to format citations (citeproc, natbib, or biblatex).


citeproc
Turn on built-in citation processing. To use this feature, you will need to have a document containing citations and a source of bibliographic data: either an external bibliography file or a list of references in the document’s YAML metadata. You can optionally also include a csl citation style file.


biblatexoptions
A list of options for BibLaTeX.


natbiboptions
One or more options to provide for natbib when generating a bibliography.


biblio-style
The bibliography style to use (e.g. \bibliographystyle{dinat}) when using natbib or biblatex.


biblio-title
The bibliography title to use when using natbib or biblatex.


biblio-config
Controls whether to output bibliography configuration for natbib or biblatex when cite method is not citeproc.


citation-abbreviations
JSON file containing abbreviations of journals that should be used in formatted bibliographies when form="short" is specified. The format of the file can be illustrated with an example:
{ "default": {
    "container-title": {
      "Lloyd's Law Reports": "Lloyd's Rep",
      "Estates Gazette": "EG",
      "Scots Law Times": "SLT"
    }
  }
}


link-citations
If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numerical styles only). Defaults to false.


link-bibliography
If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered as hyperlinks. (If an entry contains a DOI, PMCID, PMID, or URL, but none of these fields are rendered by the style, then the title, or in the absence of a title the whole entry, will be hyperlinked.) Defaults to true.


notes-after-punctuation
If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after following punctuation. For example, if the source contains blah blah (jones99?)., the result will look like blah blah.[^1], with the note moved after the period and the space collapsed.
If false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used in numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).





Footnotes







links-as-notes
Causes links to be printed as footnotes.


reference-location
Specify location for footnotes. Also controls the location of references, if reference-links is set.

block: Place at end of current top-level block
section: Place at end of current section
margin: Place at the margin
document: Place at end of document






Citation



citation
Citation information for the document itself specified as CSL YAML in the document front matter.
For more on supported options, see Citation Metadata.





Language



lang
Identifies the main language of the document using IETF language tags (following the BCP 47 standard), such as en or en-GB. The Language subtag lookup tool can look up or verify these tags.
This affects most formats, and controls hyphenation in PDF output when using LaTeX (through babel and polyglossia) or ConTeXt.


language
YAML file containing custom language translations


dir
The base script direction for the document (rtl or ltr).
For bidirectional documents, native pandoc spans and divs with the dir attribute can be used to override the base direction in some output formats. This may not always be necessary if the final renderer (e.g. the browser, when generating HTML) supports the [Unicode Bidirectional Algorithm].
When using LaTeX for bidirectional documents, only the xelatex engine is fully supported (use --pdf-engine=xelatex).





Includes







include-before-body
Include contents at the beginning of the document body (e.g. after the <body> tag in HTML, or the \begin{document} command in LaTeX).
A string value or an object with key “file” indicates a filename whose contents are to be included
An object with key “text” indicates textual content to be included


include-after-body
Include content at the end of the document body immediately after the markdown content. While it will be included before the closing </body> tag in HTML and the \end{document} command in LaTeX, this option refers to the end of the markdown content.
A string value or an object with key “file” indicates a filename whose contents are to be included
An object with key “text” indicates textual content to be included


include-in-header
Include contents at the end of the header. This can be used, for example, to include special CSS or JavaScript in HTML documents.
A string value or an object with key “file” indicates a filename whose contents are to be included
An object with key “text” indicates textual content to be included


metadata-files
Read metadata from the supplied YAML (or JSON) files. This option can be used with every input format, but string scalars in the YAML file will always be parsed as Markdown. Generally, the input will be handled the same as in YAML metadata blocks. Values in files specified later in the list will be preferred over those specified earlier. Metadata values specified inside the document, or by using -M, overwrite values specified with this option.





Metadata







keywords
List of keywords to be included in the document metadata.


subject
The document subject


title-meta
Sets the title metadata for the document


author-meta
Sets the author metadata for the document


date-meta
Sets the date metadata for the document





Rendering







from
Format to read from. Extensions can be individually enabled or disabled by appending +EXTENSION or -EXTENSION to the format name (e.g. markdown+emoji).


output-file
Output file to write to


output-ext
Extension to use for generated output file


template
Use the specified file as a custom template for the generated document.


template-partials
Include the specified files as partials accessible to the template for the generated content.


standalone
Produce output with an appropriate header and footer (e.g. a standalone HTML, LaTeX, TEI, or RTF file, not a fragment)


filters
Specify executables or Lua scripts to be used as a filter transforming the pandoc AST after the input is parsed and before the output is written.


shortcodes
Specify Lua scripts that implement shortcode handlers


keep-md
Keep the markdown file generated by executing code


keep-ipynb
Keep the notebook file generated from executing code.


ipynb-filters
Filters to pre-process ipynb files before rendering to markdown


keep-tex
Keep the intermediate tex file used during render.


extract-media
Extract images and other media contained in or linked from the source document to the path DIR, creating it if necessary, and adjust the images references in the document so they point to the extracted files. Media are downloaded, read from the file system, or extracted from a binary container (e.g. docx), as needed. The original file paths are used if they are relative paths not containing … Otherwise filenames are constructed from the SHA1 hash of the contents.


resource-path
List of paths to search for images and other resources.


default-image-extension
Specify a default extension to use when image paths/URLs have no extension. This allows you to use the same source for formats that require different kinds of images. Currently this option only affects the Markdown and LaTeX readers.


abbreviations
Specifies a custom abbreviations file, with abbreviations one to a line. This list is used when reading Markdown input: strings found in this list will be followed by a nonbreaking space, and the period will not produce sentence-ending space in formats like LaTeX. The strings may not contain spaces.


dpi
Specify the default dpi (dots per inch) value for conversion from pixels to inch/ centimeters and vice versa. (Technically, the correct term would be ppi: pixels per inch.) The default is 96. When images contain information about dpi internally, the encoded value is used instead of the default specified by this option.





Latexmk







latex-auto-mk
Use Quarto’s built-in PDF rendering wrapper (includes support for automatically installing missing LaTeX packages)


latex-auto-install
Enable/disable automatic LaTeX package installation


latex-min-runs
Minimum number of compilation passes.


latex-max-runs
Maximum number of compilation passes.


latex-clean
Clean intermediates after compilation.


latex-makeindex
Program to use for makeindex.


latex-makeindex-opts
Array of command line options for makeindex.


latex-tlmgr-opts
Array of command line options for tlmgr.


latex-output-dir
Output directory for intermediates and PDF.


latex-tinytex
Set to false to prevent an installation of TinyTex from being used to compile PDF documents.


latex-input-paths
Array of paths LaTeX should search for inputs.





Text Output







ascii
Use only ASCII characters in output. Currently supported for XML and HTML formats (which use entities instead of UTF-8 when this option is selected), CommonMark, gfm, and Markdown (which use entities), roff ms (which use hexadecimal escapes), and to a limited degree LaTeX (which uses standard commands for accented characters when possible). roff man output uses ASCII by default.