DAS Quarto tutorial

Author

Jacob Høigilt

Published

March 24, 2023

The purpose of this tutorial

Quarto is a great plain text tool to create web pages, reports, articles or books. I have written this guide primarily for humanities scholars, like those at my own department at the University of Oslo, who have already learnt Markdown and who want to use it in more advanced ways. The tutorial explains how Quarto builds on simple Markdown and shows some basic functionalities. I use Codium/VS Code as my text editor because it provides a nice built-in rendering function so you don’t have to use the command line to compile the documents you create with Quarto. I keep it simple here, but I provide links to the official Quarto documentation and other plain text resources at the end of the tutorial.

What is Quarto?

Quarto is a free and open-source scientific and technical publishing system built on the document conversion software Pandoc, which is also free and open source. It was made by Posit, the company that maintains the programming language R, and it is a development of the earlier R markdown (.rmd) standard, with which it is compatible. Quarto is geared to enable you to produce a variety of academic reports and documents in many file formats from one and the same source file, and it is also good to create ready-to-view electronic books and entire web sites. Quarto supports runnable code as part of the text in R, Python, and Julia.

The official introduction to Quarto is here.

First step: create a .qmd file with YAML header and body text

The file format used for Quarto documents is .qmd (Quarto MarkDown). Open a text editor and create a file called tutorial.qmd. Or open your terminal to open a file and give it a name simultaneously by typing the name of the text editor and the filename: codium tutorial.qmd. I use Codium or VS Code as my text editor for Quarto, since the editor has an extension that allows you to render .qmd files into different file formats directly from the editor, without using the command line. RStudio has the same functionality integrated by default in newer versions. But you can use any text editor you like, of course.

The Quarto YAML header

The typical Markdown YAML header is not very long, for example something like this:

title: A Markdown document
author: Jacob Høigilt
date: 18 March 2023

The YAML header for a Quarto document is likely to get longer because you want to include more sophisticated functionalities. Let’s look at the YAML header for this web page. Here it is:

---
title: "Miniguide to Quarto"
title-block-banner: true
author: "Jacob Høigilt"
date: today
format: 
    html:
        embed-resources: true
        toc: true
        smooth-scroll: true
        code-fold: true
        code-summary: "Show me the code"
    pdf:
        geometry: 
          - top=30mm
          - left=30mm
    docx: default
editor: source
---

Let’s start from the top, with “title-block-banner: true”. This is to tell Quarto that I want a coloured banner on the top of the page. It’s blue by default, but it can be tweaked any number of ways. If you scroll up, you will see the blue background.

The “date” field is also more versatile than in a plain markdown file. If you define it as “today”, the output html/pdf/word file will give the current date. You can of course also define it as a specific date.

The “format” field has three subfields, giving commands about how you want the document to look in html, pdf and MS Word formats. Pay attention to the indents! YAML is sensitive to indenting and one tab or space too much will result in an error. We won’t go into details about the format field here, but I thought I would just mention what the elements under “html” mean. That field is the most detailed in this document, because I intended the file to be shown as the web page you are reading now.

“embed-resources” means that the html file generated when you render the markdown document will have all the information it needs to show as a complete and nicely designed web page. If you don’t use this functionality, the rendering process will leave you with a stripped html file and an additional folder that contains a lot of information needed to display the web page properly.

“toc” is table of contents - the one you can see on the top right of this page. It is automatically generated from markdown headings.

“smooth-scroll” is self-explanatory - a better scrolling experience.

“code-fold” and “code-summary”: These have to do with how the html file I create show bits of coding included in a document (you don’t necessarily have this, particularly not in humanities research papers). If “code-fold” is true, any bits of code I write will not show. Instead, there will be an expandable line saying “show me the code”, and then the reader of the web page can click it and see the code. “code-summary” is the field that defines the text on the code-fold line - in this example, “show me the code”. I have included these because later in this tutorial I will show a simple example of how you can embed runnable code in a Quarto document.

Basics of authoring Quarto texts

You write text like you would in any Markdown document. Referencing with Better Bibtex and Zotero, covered in another tutorial, works in the same way. The same goes for the hashtag system for headings:

# Heading 1
## Heading 2
### Heading 3

Quarto automatically creates nice semi-transparent lines under second-order headings.

Let’s look at a couple of features that might be useful for a humanities scholar writing a brief or article.

Inserting and tweaking images

Let’s look at inserting an image. I have placed an image file called syria.jpg in the same folder as my Quarto document. Let us insert it here, using this command ![Syria on MENA map](syria.jpg). The text in brackets is the captio, and the whole thing shows up like this: