6.5 PDF Options

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

---
title: "Lab 1: Solutions"
format: 
  pdf:
    include-in-header: 
      - ../latex/preamble.tex         # tex template file, header file, can be used to overwrite default settings
      - text: |                       # raw LaTeX preamble added after your header file above
          \setmainfont{Georgia Pro}
    fontsize: 12pt                    # top level option
    pdf-engine: xelatex
---

See HERE for all available PDF options. All PDF options go inside the format: → pdf: chunk of the YAML.

See Metadata variables for yaml options that Pandoc recognizes.

---

Title & Author

PDF Options	Functions
title	Document title
date	User defined document date
date-format	Display format for the date in the output.
author	Author or authors of the document
abstract	Summary of document

date format

• date: Input date for Quarto to parse. It supports automatic parsing of various date formats, e.g., 2024-06-01, June 1, 2024, 01/06/2024, etc.

• date-format: Specify the output format to display in your output. E.g., MMM D, YYYY will display Jun 1, 2024. See HERE for more details and examples.

Format String	Output	Description
MMM	Jan-Dec	The abbreviated month name
D	1-31	The day of the month
DD	01-31	The day of the month, 2-digits
YYYY	2024	The four-digit year

Add email to author:

Redefine \maketitle to add email address to the author, adjust spacing, font size, etc.

author: "\\textnormal{Menghan Yuan\\thanks{\\href{mailto:menghan.yuan@nord.no}{menghan.yuan@nord.no}}}"
format: 
  pdf:
    -text: |
      \usepackage{hyperref}
      
      \makeatletter
      % Keep KOMA-Script title fonts, but tighten the vertical spacing.
      \def\@subtitle{}
      \renewcommand{\subtitle}[1]{\gdef\@subtitle{#1}}

      \renewcommand{\maketitle}{%
        \begingroup
        \vspace*{-1em}%
        \begin{center}
          {\usekomafont{title}\huge \@title \par}
          {\usekomafont{subtitle}\large \@subtitle \par}
          \vspace{0.35em}
          {\usekomafont{author}\small \@author \par}
          \vspace{0.15em}
          {\usekomafont{date}\small \@date \par}
        \end{center}
        \@thanks
        \endgroup
      }
      \makeatother

If you want to adjust the vertical spacing between \maketitle and the body, you can add \vspace after \end{center} and before \@thanks in the code above.

Here I renew the \maketitle command:

• move title up by 1em
• make the title page components more compact
  • \usekomafont keeps the default KOMA-Script fonts.
  • smaller font size for author and date
• add \@thanks in the footnote to display the email address.

Syntax explain:

• \makeatletter: treats @ as letter; allows the use of @ in command names.

  \makeatother: treats @ as other.

• Define a new command \subtitle to allow for subtitle in the title page.

  \def\@subtitle{}
  \renewcommand{\subtitle}[1]{\gdef\@subtitle{#1}}

  • \def\@subtitle{} initializes the \@subtitle command to be empty.

  • \gdef globally defines \@subtitle to be the argument passed to \subtitle. This allows you to use \subtitle{Your Subtitle} in your .qmd file, and it will be included in the title page.

  • If you use scrartcl document class, it already defines \subtitle, the code above is not necessary.

    For older document classes, e.g., article, you need to define \subtitle yourself as shown above.

Format Options

PDF Options	Functions
pdf-engine	Specify the PDF engine to use. The default is xelatex. Options include pdflatex, xelatex, and lualatex.
documentclass	Defaults to scrartcl
keep-tex	Keep the intermediate tex file used during render.

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.

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

Includes

PDF Options	Functions
include-in-header	Include contents at the end of the header. Specify your pdf template here.
include-before-body	Include contents at the beginning of the document body, i.e., after \begin{document}.
include-after-body	Include contents at the end of the document body, i.e., before \end{document}.
metadata-files	Read metadata from the supplied YAML (or JSON) files.

Subkeys for include-in-header:

• file: path to a file to include at the end of the header.

  • Useful if you have template files.

  • Can have several files to include, e.g., preamble.tex for package setup and macros.tex for custom macros.

  • You can use relative paths or absolute paths.

    Absolute paths can be lengthy, one workaround is to

    1. put your template files in a shared folder

    2. create a symbolic link to the shared folder in your project directory:

       ln -s /path/to/shared/latex/preamble.tex ./latex/preamble.tex

    3. use the symbolic link in your yaml:

       format:
         pdf:
           include-in-header:
             - file: ./latex/preamble.tex

• text: |: include raw latex content in the YAML header.

  | indicates that the content is in multiple lines.

• If you omit file: or text:, Quarto assumes file: by default.

include-in-header 优先级最高，高于 Quarto top level pdf options. 比如既设置了 mainfont: Charter，又在 include-in-header 中设置了 \setmainfont{Georgia Pro}，两者会冲突，但由于 include-in-header 优先级更高，所以最终的字体是 Georgia Pro。

如果你的 include-in-header:file 也中设置了字体，那么最后定义的字体会覆盖之前的设置。即谁后定义的字体，谁就生效。

Use example

format:
  pdf:
    include-in-header:
      - text: |
          \usepackage{eplain}
          \usepackage{easy-todo}
      - file: packages.tex
      - macros.tex            # assume file by default
    include-before-body:
      - file: before-body.tex
      - text: |
          \vspace*{-2em}      % reduce space btw title and body

• Note that you need the dash - before text: and file: to indicate a list of items.

---

Add logo to the title page

Use fnacyhdr package to add a logo to the title page.

format: 
  pdf:
    include-in-header: 
      - text: |
          \usepackage{graphicx}
          \usepackage{fancyhdr}
          \usepackage{ifthen}
          \pagestyle{fancy}
          \fancyhead[L]{\ifthenelse{\value{page}=1}{\includegraphics[height=1.5cm]{nordlogoen.jpg}}{}}
    include-before-body:
      - text: |
          \vspace*{-2em}
          \thispagestyle{fancy}

• \vspace*{-2em} moves the body up by 2em to reduce the space between the title and the body.
• \thispagestyle{fancy} applies the fancy page style to the title page, which allows us to use \fancyhead to add the logo to the left header of the first page.

If you want to customize the title page further, see HERE.

---

Note: Any packages specified using includes that you don’t already have installed locally will be installed by Quarto during the rendering of the document.

header-includes: | is a pandoc variable for including raw LaTeX code in the document header.

• use example in quarto doc
• pandoc doc for header-includes

Use example:

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}

Format & Typesettings

PDF Options	Functions
toc-depth: 3	Specify the number of section levels to include in the table of contents. The default is 3
number-sections: false	Number section headings rendered output. By default, sections are not numbered.
number-depth	By default, all headings in your document create a numbered section.
Fonts
fontsize	base font size
mainfont	main font familty
sansfont	sans serif font family
mathfont	math font family
monofont	monospaced font family
CJKmainfont	main font family for Chinese, Japanese, and Korean (CJK) characters, supported by xecjk package
linestretch	line spacing using setspace package

Tables

PDF Options	Functions
df-print	Method used to print tables in Knitr engine documents. - default: Use the default S3 method for the data frame. - kable: Default method. 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.

Engine Binding

PDF Options	Functions
keep-tex: false	Whether to keep the intermediate tex file used during render. Defaults to false.

The .tex file generated looks cluttered as it includes all default settings imposed by Quarto. I rarely use the .tex file, but can be useful when you want to debug or share tex files with others.

Q: Are there incremental rendering options for pdf output?
A: [Unresolved] for a single file. For a project with multiple files, you can set freeze: auto in _quarto.yml to only re-render changed files. See Only re-render changed files for details.

---

Q: How to print dollar sign in pdf output?
A: qmd supports $ directly. No need to escape. If it fails, try \$ or \\$.

---

After rendering, the following info will appear in the console:

pandoc 
  to: latex
  output-file: lab1_solutions.tex
  standalone: true
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  
metadata
  documentclass: scrartcl
  classoption:
    - DIV=11
    - numbers=noendperiod
  papersize: letter
  header-includes:
    - \KOMAoption{captions}{tableheading}
  block-headings: true
  title: 'Lab 1: Solutions'
  fontsize: 12pt

By default, Quarto uses the scrartcl document class and letter paper size for pdf output.

Note that documentclass: scrartcl is the KOMA-Script article class. KOMA-Script classes have good looking default settings, and are highly customizable.

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

---

6.5.1 Title Margin

One issue is it might have too wide margins around the title.

To reduce the margin above the title, add the following line to your preamble.tex file:

% reduce title top margin
\usepackage{xpatch}
\makeatletter
\xpatchcmd{\@maketitle}{\vskip2em}{
    % Insert here the space you want between the top margin and the title.
    \vspace{-2em} % Example of smaller margin. 
}{}{}
\makeatother

Refer to HERE for redefining the \maketitle command to further customize the title page, e.g., more refined control of spacing, add a logo, change font size, etc.

---

To reduce the margin below the title, in individual qmd file, add the following line after the YAML header:

• fenced divs

  ::: {=latex}
  \vspace{-6em}
  :::

• code chunks

  ```{=latex} 
  \vspace{-6em}
  ```

For pdf output, it is possible to write LaTeX code directly in Markdown document using fenced divs or code chunks with {=latex}.

• Don’t forget the equal sign before latex.

ref: R Markdown Cookbook: Section 6.11 Write raw LaTeX code

---

6.5.2 Templates

See HERE for an overview of how to set template for tex files.

• pakage setup
• article typsetting

Starter template for qmd file.

• yaml header
• structure of your qmd

---

6.5.3 Add Appendices

\newpage

# Appendices {.unnumbered}

\appendix
\renewcommand{\thesubsection}{\Alph{subsection}}
\setcounter{table}{0}
\renewcommand{\thetable}{\thesection\arabic{table}}
\setcounter{figure}{0}
\renewcommand{\thefigure}{\thesection\arabic{figure}}

## Optimal Portfolio R Code

• # Appendices {.unnumbered} creates a title for the appendices section without a section number.
• Use \appendix to reset the section counter to 0 and \renewcommand{\thesubsection}{\Alph{subsection}} to change the section numbering to letters (A, B, C, …).
• Similarly, reset the table and figure counters and change their numbering to include the section letter “A”, “B”, … as a prefix.
• Finally, use ## Optimal Portfolio R Code to create an appendix section for your first appendix. The # Appendices will be level one heading, and ## Optimal Portfolio R Code will be level two heading under the appendices section.

6.5.4 Add TOC

To show TOC pane in pdf, you can either set in YAML or in preambles.

• YAML

  hyperrefoptions:
    - bookmarksopen=true
    - bookmarksopenlevel=3

• preambles

  % Configure hyperref for expanded bookmarks
  % Note that this only works for Adobe Acrobat Reader
  \usepackage{hyperref}
  \hypersetup{
    bookmarksopen = true, % show TOC with all the subtrees expanded
    bookmarksopenlevel = 2 % level to which bookmarks are open
  }

6.5.5 YAML templates

With logo in the title page

---
title: "Your Title"
subtitle: "Optional Subtitle"
author: "\\textnormal{Menghan Yuan\\thanks{\\href{mailto:menghan.yuan@nord.no}{menghan.yuan@nord.no}}}"
date: "2026-06-01"
date-format: "MMM D, YYYY"
from: markdown+tex_math_single_backslash
format: 
  pdf:
    include-in-header: 
      - ../../_shared-resources/latex/preamble.tex
      - text: |
          \setmainfont{Georgia Pro}
          \usepackage{graphicx}
          \usepackage{fancyhdr}
          \usepackage{ifthen}
          \pagestyle{fancy}
          \fancyhead[L]{\ifthenelse{\value{page}=1}{\includegraphics[height=1.5cm]{nordlogoen.jpg}}{}}
          \renewcommand{\headrulewidth}{0pt}
          \makeatletter
          % Keep KOMA-Script title fonts, but tighten the vertical spacing.
          \renewcommand{\maketitle}{%
            \begingroup
            \vspace*{-1em}%
            \begin{center}
              {\usekomafont{title}\huge \@title \par}
              {\usekomafont{subtitle}\large \@subtitle \par}
              \vspace{0.35em}
              {\usekomafont{author}\small \@author \par}
              \vspace{0.15em}
              {\usekomafont{date}\small \@date \par}
            \end{center}
            \@thanks
            \endgroup
          }
          \makeatother
    include-before-body:
      - text: |
          \thispagestyle{fancy}
    keep-tex: true
    fontsize: 12pt
---

---