Why define a document style?

Starting with a plain document

Quarto is an open-source scientific and technical publishing system that allows you to combine text, images, code, plots, and tables in a fully-reproducible document. Quarto has support for multiple languages including R, Python, Julia, and Observable. It also works for a range of output formats such as PDFs, HTML documents, websites, presentations, …

---
title: "My document"
format: html
---

Content goes here.

Built-in themes for HTML output

Quarto includes 25 themes from the Bootswatch project for HTML output.

See quarto.org/docs/output-formats/html-themes.html for a complete list.

There are also 11 built-in themes for Revealjs presentations.

Built-in themes for HTML output

---
title: "My document"
format:
  html:
    theme: slate
---

Content goes here.

Built-in options for HTML output

---
title: "My document"
format:
  html:
    backgroundcolor: lightblue
---

Content goes [here](https://github.com/).

Adding your own CSS styling

---
title: "My document"
format:
  html:
    theme: [morph, styles.scss]
---

Content goes [here](https://github.com/).

/*-- scss:defaults --*/
$link-color: #800080;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -3px -3px 0 rgba(0, 0, 0, .3);
}

Built-in options for PDF output

---
title: "My document"
format:
  pdf:
    urlcolor: "red"
---

Content goes [here](https://github.com/).

Adding your own LaTeX styling

---
title: "My document"
format:
  pdf:
    include-in-header: 
       - "styles.tex"
---

# Section 1

Content goes [here](https://github.com/).

%% load packages
\usepackage{xcolor}
\usepackage{sectsty}

%% Let's define some colours
\definecolor{MyPurple}{HTML}{800080}

%% Section font colour
\sectionfont{\color{MyPurple}}

Adding your own LaTeX styling

In the upcoming Quarto 1.4 release, you can also create PDFs using Typst (no LaTeX!).

Using Quarto extensions

Extensions are a powerful way to modify and extend the behavior of Quarto. Extensions can be used to add styling to your documents.

Installing Quarto extensions

There are different ways to distribute Quarto extensions. Many are distributed via GitHub.

To install an extension, run the following in the command line:

quarto install extension username/repository

For example, to install my PrettyPDF extension:

quarto install extension nrennie/PrettyPDF

Using Quarto extensions

This creates an _extensions folder in your current directory.

You then need to edit the YAML at the top of the Quarto document, to tell it to use the extension:

---
format: PrettyPDF-pdf
---

---
format:
  PrettyPDF-pdf:
    keep-tex: true
---

Using Quarto extensions

Need to reformat to a completely different style?

---
format: PrettyPDF-pdf
---

---
format: PrettierPDF-pdf
---

Installing Quarto templates

Some Quarto extensions (especially style extensions) come with a template file that changes the YAML for you.

quarto use template username/repository

For example, to use my PrettyPDF template:

quarto use template nrennie/PrettyPDF

This creates an _extensions folder in your current directory and a .qmd file with the correct YAML.

Where do I find Quarto extensions?

Why build your own extension?

What are the components of a (style) extension?

The essentials…

• _extensions folder

• _extension.yml file

What are the components of a (style) extension?

The folder structure might look like this:

├── template.qmd
└── _extensions/
    └── Extension Name/
        ├── _extension.yml
        └── Other files...

What are the components of a (style) extension?

The template.qmd file

---
title: "Pretty PDFs with Quarto"
format: PrettyPDF-pdf
---

## Quarto

Quarto enables you to weave together content and executable code into a finished 
document. To learn more about Quarto see <https://quarto.org>.

### Running Code

When you click the **Render** button a document will be generated that includes both 
content and the output of embedded code. You can embed code like this:

```{r}
1 + 1
```

The _extension.yml file

title: PrettyPDF
author: Nicola Rennie
version: 0.0.1
contributes:
  formats: 
    pdf:
      include-in-header: 
       - "PrettyPDF.tex"
      include-before-body:
       - "pagestyle.tex"
      toc: false
      code-block-bg: light
      linkcolor: highlight
      urlcolor: highlight

The PrettyPDF.tex file

% load packages
\usepackage{geometry}
\usepackage{xcolor}
\usepackage{eso-pic}
\usepackage{fancyhdr}
\usepackage{sectsty}
\usepackage{fontspec}
\usepackage{titlesec}

%% Set page size with a wider right margin
\geometry{a4paper, total={170mm,257mm}, left=20mm, top=20mm, bottom=20mm, right=50mm}

The PrettyPDF.tex file

%% Let's define some colours
\definecolor{light}{HTML}{E6E6FA}
\definecolor{highlight}{HTML}{800080}
\definecolor{dark}{HTML}{330033}

%% style the chapter/section fonts
\chapterfont{\color{dark}\fontsize{20}{16.8}\selectfont}
\sectionfont{\color{dark}\fontsize{20}{16.8}\selectfont}
\subsectionfont{\color{dark}\fontsize{14}{16.8}\selectfont}
\titleformat{\subsection}
  {\sffamily\Large\bfseries}{\thesection}{1em}{}[{\titlerule[0.8pt]}]

The PrettyPDF.tex file

%% Let's add the border on the right hand side 
\AddToShipoutPicture{% 
    \AtPageLowerLeft{% 
        \put(\LenToUnit{\dimexpr\paperwidth-3cm},0){% 
            \color{light}\rule{3cm}{\LenToUnit\paperheight}%
          }%
     }%
     % logo
    \AtPageLowerLeft{% start the bar at the bottom right of the page
        \put(\LenToUnit{\dimexpr\paperwidth-2.25cm},27.2cm){% move it to the top right
            \color{light}\includegraphics[width=1.5cm]{_extensions/nrennie/PrettyPDF/logo.png}
          }%
     }%
}

Check it works!

After pushing code to GitHub, install the extension:

quarto use template nrennie/PrettyPDF

Render the document:

quarto render document.qmd

Check it works!

Tips for building extensions

Things I learnt the hard way…

Useful links

Slides: nrennie.rbind.io/talks/bplim-quarto-extensions

Blog: nrennie.rbind.io/blog/making-pretty-pdf-quarto

PrettyPDF extension: github.com/nrennie/PrettyPDF

Building extensions guide: quarto.org/docs/extensions/creating