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:

Note that for the caption to be shown correctly and the image to be centered, you must place the code for inserting the image on a separate line, separated by blank lines above and underneath. The image is sized according to the limits set by the page or frame, as you can see. Suppose I want to customize the size. I do that by specifying the number of pixels. When supplying width, height is calculated automatically to maintain the width/height ratio:

![Syria on MENA map](syria.jpg){width=100}.

For more options regarding images, including alignment, see the relevant Quarto section

Lists

These are made with dashes, and output is with bullets:

- Apples
- Pears
- Oranges

Apples
Pears
Oranges

References and cross references

References are made the same way as in plain markdown documents. For a guide on how to use markdown with Zotero and Better Bibtex, see the guide on this site.

Cross references is a neat feature of Quarto. Suppose I want to refer with a hyperlink to the big image of the Middle East map above. First, I need to add an identifier to the image link, like this: ![Syria on MENA map](syria.jpg){#fig-syria}. Here, {#fig-syria} is the identifier. Then I simply use the following syntax to refer to it: @fig-syria. Like this: See Figure 1 for a map of Syria and its neighbours.

You can read more about cross referencing in the Quarto documentation, here.

Very often we would like to link to some other web page. You do this by using the standard markdown syntax:

My name is Jacob Høigilt and I am professor of Arab studies 
at UiO. My website is 
[here](https://www.hf.uio.no/ikos/english/people/aca/middle-east-studies/temporary/jacobhoi)

This is how it looks when rendered: My name is Jacob Høigilt and I am professor of Arab studies at UiO. My website is here.