PDF Basics

Overview

use thepdf format to create pdf output . For example :

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

This example is highlights highlight a few of the option available for pdf output . This article is covers cover these andother option in detail . See the pdf format reference for a complete list of all available option .

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 that while we will focus here exclusively on the use of latex to create PDFs ,Pandoc also has support for create pdf using ConTeXt ,roff ms ,or html ( via wkhtmltopdf ) . See the Pandoc documentation on create a pdf for additional detail .

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:

See the article on PDF Engines for detail on using other TeX distribution andpdf compilation engine .

Document Class

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

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

format:
  pdf:
    documentclass: scrartcl
    papersize:  letter

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

Setting your documentclass to eitherbook orscrbook will automatically handle many of the common needs for printing andbinding PDFs into a physical book (i.e.,chapters start on odd pages,alternating margin sizes,etc).

See the Output option section below for additional detail on customize latex document option .

Table of Contents

use thetoc option to include an automatically generated table of contents in the output document. use thetoc-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:

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

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

# # # More option { .unnumbere .unliste }

Section Numbering

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

use thenumber-depth option to specify the deep level of head to add number to ( by default all heading are number ) . For example :

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

### More option {.unnumbered}

Syntax Highlighting

Pandoc is highlight will automatically highlight syntax in fence code block that are mark with a language name . For example :

```python
1 + 1
```

Pandoc is provide can provide syntax highlighting for over 140 different language ( see the output ofquarto pandoc --list - highlight - language for a list of all of them). If you want to provide the appearance of a highlighted code block for a language not supported,just use default as the language name.

You can specify the code highlighting style using highlight-style andspecifying 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:

Highlighting themes can provide either a single highlighting definition ortwo definitions,one optimized for a light colored background andanother 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 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 anddark themes:

Code Annotation

You can add annotations to lines of code in code blocks andexecutable code cells. See Code Annotation for full details.

Output option

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

• Specifying document classes andtheir options

• include list of figure andtable

• Using the geometry andhyperref packages

• Numerous options for customizing fonts andcolors.

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
    mainfont:  Times New Roman
    colorlink: true
---

See the Pandoc documentation on metadata variable for latex for documentation on all available option .

font

Using xelatex,the default engine,or the lualatex engine,you can specify fonts with the YAML options:

Values for these options should be the family name of system installed fonts. For example:

---
format: 
  pdf:
    mainfont: "Times New Roman"
---

font are set using the fontspec package. You is set can setadditional font features using the corresponding <fontoption>options key. For example,you could set headings to the color #39729E:

---
format: 
  pdf:
    sansfont: "Open Sans"
    sansfontoptions: 
      -  Color=39729E
---

pdflatex

If you is use use thepdflatex engine,use the fontfamily option to specify a font from the The LaTeX Font Catalogue. For example:

---
title:  pdflatex fonts
format:
  pdf:
    pdf-engine:  pdflatex
    fontfamily: anttor
---

Unicode Characters

By default,Quarto uses the xelatex engine to produce PDFs from LaTeX. xelatex has native support for unicode characters,but it is possible some customization will be required in order to properly typeset specific unicode characters. In particular,it is important that you use a font that supports the characters that you using in your document. To identify fonts on your system that support specific language characters,you can use the following command:

fc-list  : lang=<lang> family

Where <lang> is a ISO 639 language code. For example,to see a list of fonts that support Japanese characters,use:

Select a font name from the list anduse that as the document’s main font:

---
title : Unicode test
format:  pdf
mainfont :  " Hiragino Sans GB "
---

# # Test document

青黑體簡體中文 , ヒラギノ角

Another common example of Unicode characters are documents that include Greek symbols:

---
format:  pdf
---

## α

```r
α <- 3
```

α is a great constant.
```

follow the same process as above to discover font that support Greek :

Then set the appropriate font options:

---
format: 
    pdf :
    mainfont : "EB Garamond"
    sansfont: "Open Sans"
     monofont : " Roboto Mono "
---

(These particular fonts are available from Google font.)

With fonts with appropriate support,Greek symbols render correctly in headings,the main text andcode cells:

greek symbol in a render PDF

citation

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

format:
  pdf: 
    cite-method:  biblatex

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

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

option

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

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 andpassed unchanged to the LaTeX writer.

While it’s very convenient to use raw LaTeX,raw LaTeX is ignored when rendering to other formats like HTML andMS 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 include section below describes how to include \usepackage commands for these packages in your document.

latex include

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

You can specify a single file ormultiple files for each of these options directly,or use the file: subkey. To include raw content in the YAML header,use the text subkey. When using text :,add the | character after text : to indicate that the value is a multi-line string. If you omit file: ortext :,Quarto assumes you are providing a file.

For example:

format:
  pdf:
    include-in-header:
      - text: |
          \usepackage{eplain}
          \usepackage{easy-todo}
      - file:  packages.tex
      - macros.tex 

Any packages is includes specify using include that you do n’t already have instal locally will be instal by Quarto during the rendering of the document .

latex output

If you is want 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 thelatex 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 thepdf 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 .

Both techniques will also produce all LaTeX temporary files,including .bbl files andso on,that might be required by a publisher that wants LaTeX sources.

Unicode Characters

By default,Quarto uses the xelatex engine to produce PDFs from LaTeX. xelatex has native support for unicode characters,but it is possible some customization will be required in order to properly typeset specific unicode characters. In particular,it is important that you use a font that supports the characters that you are using in your document. To identify fonts on your system that support specific language characters,you can use the following command:

For example,to see a list of fonts that support Japanese characters,use:

Select a font name from the list anduse that as the document’s main font,like:

---
title : Unicode test
format:  pdf
mainfont :  " Hiragino Sans GB "
---

# # Test document

青黑體簡體中文 , ヒラギノ角