What to expect during this workshop

The workshop will run for 2 hours.

• Combines slides, live coding examples, and exercises for you to participate in.

• Ask questions in the chat throughout!

What you need for this workshop

• Working installation of Quarto, and are able to render an HTML document. If not, download from quarto.org.

• Able to run command line operations e.g. via Terminal in RStudio.

• Ideally, a working installation of one of R, Python, or Julia.

Workshop resources

Course website: nrennie.rbind.io/training-quarto-extensions

What is Quarto?

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, …

What is Quarto?

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

Content goes here.

Why customise document style?

Consistency

Documents from different authors look the same.

Professionalism

Default options usually look like the default options.

Accessibility

Information can often be presented in better ways when designed actively.

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/).

Live demo!

• Create a Quarto document which outputs to HTML format.
• Include some text and a code block (in a programming language of your choice).
• Edit the YAML to use the darkly Bootswatch themes.
• Further edit the YAML to change the monobackgroundcolor.

Exercise 1

• Create a Quarto document which outputs to HTML format.

• Include some text and a code block (in a programming language of your choice).

• Edit the YAML to use one of the Bootswatch themes. See quarto.org/docs/output-formats/html-themes.html for options.

• Further edit the YAML to change the linkcolor.

• Bonus: edit other YAML options to customise further.

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);
}

Adding your own docx styling

---
title: "My document"
format:
  docx:
    reference-doc: styles.docx
---

Content goes here.

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!).

Live demo!

• Create a styles.scss file.

• Add the styles.scss file to the YAML options in your Quarto file.

• Create some CSS variables and write some simple CSS rules in the styles.scss file.

  • Change the text colour to #000080.
  • Add a left border to code blocks with colour #FE019A.
  • Underline the title with a #FE019A coloured line.

Exercise 2

• Create a styles.scss file.

• Add the styles.scss file to the YAML options in your Quarto file.

• Create some CSS variables and write some simple CSS rules in the styles.scss file.

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 add username/repository

For example, to install my PrettyPDF extension:

quarto add 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?

Live demo!

• Install the PrettyPDF template by Nicola Rennie using quarto add nrennie/PrettyPDF.

• Edit the YAML of the .qmd file to use the extension.

• Re-render the document.

Exercise 3

• Install the LCARS template by Michael McCarthy using quarto add mccarthy-m-g/quarto-lcars-theme.

• Edit the YAML of your .qmd file to use the extension. See github.com/mccarthy-m-g/quarto-lcars-theme for more information.

• Re-render your document.

• Bonus: browse the Awesome Quarto list and choose a different extension: github.com/mcanouil/awesome-quarto

Why build your own extension?

Reduce repetition

Don’t copy and paste commonly used YAML options between documents.

Share with others

Everybody in an organisation can create similar outputs without having to adjust the style themselves.

Version control style

Changes to designs can be tracked alongside code.

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}

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

%% 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}
          }%
     }%
}

%% Style the page number
\fancypagestyle{mystyle}{
  \fancyhf{}
  \renewcommand\headrulewidth{0pt}
  \fancyfoot[R]{\thepage}
  \fancyfootoffset{3.5cm}
}
\setlength{\footskip}{20pt}

%% 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]}]
  
% left align title
\makeatletter
\renewcommand{\maketitle}{\bgroup\setlength{\parindent}{0pt}
\begin{flushleft}
  {\sffamily\huge\textbf{\MakeUppercase{\@title}}} \vspace{0.3cm} \newline
  {\Large {\@subtitle}} \newline
  \@author
\end{flushleft}\egroup
}
\makeatother

%% Use some custom fonts
\setsansfont{Ubuntu}[
    Path=_extensions/nrennie/PrettyPDF/Ubuntu/,
    Scale=0.9,
    Extension = .ttf,
    UprightFont=*-Regular,
    BoldFont=*-Bold,
    ItalicFont=*-Italic,
    ]

\setmainfont{Ubuntu}[
    Path=_extensions/nrennie/PrettyPDF/Ubuntu/,
    Scale=0.9,
    Extension = .ttf,
    UprightFont=*-Regular,
    BoldFont=*-Bold,
    ItalicFont=*-Italic,
    ]

Live demo!

• Create an _extensions folder in the same directory as your .qmd file. (You may already have one from Exercise 3).
• Create another folder inside the _extensions folder with a name that will be the name of your extension e.g. PrettyHTML.
• Move your styles.scss file from Example 2 into the PrettyHTML folder.
• Create an _extension.yml file in the PrettyHTML folder.
• Write the YAML code specifying the: extension title, author name, version number, and contribution (HTML format with the styles.scss styling)
• Edit the YAML in the .qmd file to use this extension.

Exercise 4

• Create an _extensions folder in the same directory as your .qmd file.

• Create another folder inside the _extensions for your extension e.g. PrettyHTML.

• Move your styles.scss file from Exercise 2 into the PrettyHTML folder.

• Create an _extension.yml file in the PrettyHTML folder.

• Write the YAML code specifying the extension title, author name, version number, and contribution (HTML format with the styles.scss styling).

• Edit the YAML in the .qmd file to use this extension.

Sharing extensions with others

There are two ways to distribute extensions:

• Publish your extension in a public GitHub repository.

quarto add quarto-ext/lightbox

• Bundle your extension into a .zip or .tar.gz archive.

quarto add https://gitlab.com/cooltools/shorty/-/archive/main/shorty-main.zip

See quarto.org/docs/extensions/distributing.html.

Alternatively, as an R (or Python/Julia) package: github.com/jthomasmock/octavo

Tips for building extensions

Things I learnt the hard way…

• Things get confusing when you build an extension with same name as your GitHub username.

• (Font) paths are hard.

• You’ll likely want multiple output formats in one extension (e.g. book and pdf).

Workshop resources

Course website: nrennie.rbind.io/training-quarto-extensions