Formatting options for PDF output

[jpmorr]

What is the best way to specify formatting options for the pdf output? For example, if you want to change the title 1 / title font size and colour, in a book would it be best to do this via the include-in-header: and include all your options in a .tex file or should these be specified in some manner through the yaml parameters for a book?

[mcanouil]

Use Pandoc template syntax.

https://pandoc.org/MANUAL.html#template-syntax

In your yaml:

margin: 3cm

In you partial (tex):

$if(margin)$
\usepackage[margin=$margin$]{geometry}
$endif$

See also https://quarto.org/docs/journals/templates.html.

[eeholmes]

This depends on the document class. The default document classes for Quarto are scrartcl and scrbook which are KOMA classes. In this case putting something like

\setkomafont{title}{\HUGE\bfseries}

in your header would/should change the title size. I am pretty subtitle works similarly. The, ah, problem with this is that everything breaks once you switch to a non-koma document class. Note, I don't know if there is a yaml variable for the title size, if there is it is likely to be tied to the KOMA classes that are default. So don't be surprised if it breaks if you switch to another document class.

For this reason, latex users often ditch \maketitle and create their title pages with \begin{titlepage} ... \end{titlepage}. Here you have full control of the title page and you can make the font sizes what you want. This will work across all document classes.

Here is an example title page where the title size is customized:
https://github.com/nmfs-opensci/quarto_titlepages/blob/main/titlepages/thesis-static/_titlepage.tex

How do you force Pandoc to use this title page and not use whatever it is using?

First, you need to know that Pandoc runs a template partial called before-body.tex that appears just after \begin{document}. This tex file is pretty simple
https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/pdf/pandoc/before-body.tex
For our purposes the main thing it does is call \maketitle. We don't want that.

So we pass in our own before-body.tex in the template-partials: ["before-body.tex"]. This will replace the one that Pandoc uses.

Here is a simple example, where we make a static title page. Static means it is not going to use things like title or author in the yaml.

YAML

---
title: Not used
subtitle: Not used
author:
  - name: Not used
editor: source
format:
  pdf:
    documentclass: scrbook
    template-partials:
      - "before-body.tex"
---

before-body.tex

\begin{titlepage}
   \begin{center}
        \vspace*{1cm}
            
        \Huge
        \textbf{Thesis Title}
            
        \vspace{0.5cm}
        \LARGE
        Thesis Subtitle
            
        \vspace{1.5cm}
            
        \textbf{Author Name}
            
        \vfill
            
        A thesis presented for the degree of\\
        Doctor of Philosophy
            
        \vspace{0.8cm}
            
        \includegraphics[width=0.4\textwidth]{logo.png}
            
        \Large
        Department Name\\
        University Name\\
        Country\\
        Date
            
    \end{center}
\end{titlepage}

The tex file that Pandoc generates will look like so

<<a bunch of Pandoc header stuff that hopefully won't cause trouble>>

<<any header stuff we pass in in include-in-header>>

\begin{document}

\begin{titlepage}
 <<all that stuff in our before-body.tex>>
\end{titlepage}

<<the body of text coming from our qmd>>

\end{document}

Hopefully this also helps you see how you can include the preface. There are many different ways that one might include a preface in a book.

One way is add \include{preface.tex} after \end{titlepage} in before-body.tex. However you might want this in the front matter (so it has roman numbers for page numbers). In that case you can do,

\begin{frontmatter}
\begin{titlepage}
 <<all that stuff in our before-body.tex>>
\end{titlepage}
\include{preface.tex}
\end{frontmatter}

I added some tips on customizing PDF frontmatter here:
https://nmfs-opensci.github.io/quarto_titlepages/02-how-it-works.html

[jpmorr]

Thanks. I'm already using great-wave and wanted to add some additional information to the verso page.

I had hoped that I could just do the following in the yaml:

book:
  title: "My book"
  subtitle: "A really good book" 
  edition: "Third"
  isbn: xxx-xxxxxxxx
  author:
   - name: Mr. Jones

And then on the _titlepage.tex I could just do something like this:

% Title and subtitle
{\huge\bfseries\nohyphens{$title$}}\\[1.25\baselineskip] 
$if(subtitle)${\large\textit{$subtitle$}}\\[2\baselineskip]$endif$
$if(edition)${\large\textit{$edition$}} Edition\\[2\baselineskip]$endif$
$if(isbn)${\large\textit{ISBN:}} $isbn$\\[2\baselineskip]$endif$

But unfortunately that doesn't work as the edition and isbn information are not found in the yaml parameters. I guess you can only access a predefined list of parameters and can't simply create your own?

With regards to formatting I was thinking more along the lines of the Chapter and Section and font options and how these should be best handled. I was thinking there should be some way of setting these things once in the yaml that would apply to both the html and pdf output.

Typically in a latex document you would do something like this:

\definecolor{color_lightgrey}{RGB}{242, 242, 242}
\titleformat{\chapter}{\LARGE\bfseries\scshape\color{color_lightgrey}}{\thechapter}{1em}{}[\titlerule]
\titleformat{\section}{\color{color_lightgrey}\Large\bfseries\uppercase}{\thesection}{1em}{}
\titleformat{\subsection}{\color{color_lightgrey}\large\bfseries\uppercase}{\thesubsection}{1em}{}
\titleformat{\subsubsection}{\color{color_lightgrey}\bfseries\uppercase}{\thesubsubsection}{1em}{}

and you could then place that in a file via include-in-header: - I think this should work but haven't tested yet as it may clash with the KOMA document class.

[cderv]

But unfortunately that doesn't work as the edition and isbn information are not found in the yaml parameters

Did you try adding those at the first level of the YAML not under the book key ?

Otherwise, metadata-files is a type of include you can use to add some variables for Pandoc (https://quarto.org/docs/reference/formats/pdf.html#includes) from an external file. However, putting them at the first level of the main YAML file should work IMO.

[eeholmes]

I created yaml variables on the fly within the pdf: format part and it just worked. Maybe you have to do something extra to define ones under book: ?

Putting those latex command in include-in-header should work as long as you add \usepackage{titlesec}. I am pretty sure that \titleformat is from the titlesec package, no?

[eeholmes]

@jpmorr Ok I figured out the yaml variable bit. Because you added isbn under book, and it's not one of the pre-defined ones, you need to use book.isbn so this works in the template

$if(book.isbn)${\large\textit{ISBN:}} $book.isbn$\\[2\baselineskip]$endif$

[cderv]

yes variables under pdf: key will be cleverly merged with usual metadata. For the others, it needs to be access with the all key in the template. Or put at first level of YAML, or in another file passed using the metadata-file.

Thanks for the confirmation @eeholmes !

[eeholmes]

I tested in a non-Quarto project and adding yaml parameter worked.

This is the yaml at top of the doc

---
title: quarto_titlepages
subtitle: Templates for title pages and covers
isbn: 123

<<left off the rest of the yaml>>
---

[eeholmes]

If you are doing this in a project, then change the template to

$if(book.isbn)${\large\textit{ISBN:}} $book.isbn$\\[2\baselineskip]$endif$

with yaml

book:
  title: quarto_titlepages
  subtitle: Templates for title pages and covers
  isbn: 123

[eeholmes]

Hmm, I should probably add $if(project.type=="book")$ to my template. Sadly (horribly), pandoc template doesn't allow that kind of logic as there is no == logic. Pretty sure I need to employ a lua filter to get that kind of if statement.

[cderv]

Passing variable for template under some keys specific to Quarto project is not the more portable way.
Using a Lua filter on metadata should definitely allow you to add some logic and organize your metadata for using in the template. Good idea!