Getting Started
In this workshop we will need to work publicly (which is scary). We will create a public github repo to work from, and in the first stages of this workshop we will generate a local file (for ease, we will create a basic .html file, but the concepts will be the same as for creating a word doc or pdf). We will then update this file to become a webpage which to function as an ‘about me’ page or to showcase your work. I recommend pinning this repo (which we will demonstrate) so that when someone visits your github, they can view useful information about you.
Set up new public repo and open an R project
Go to github, under “Repositories”, click New, give your new repo a name and description, and make sure the “public” box is checked (this should occur by default).
Click on the green “Code” button, and copy the url for the repo.
From RStudio, go File > New Project > Version Control > Git. Paste in the repo URL, provide a project directory name, and select the location for the project. Initialise the project when ready.
First quarto doc
We can now create our first quarto (.qmd) file. Under File > New File, click Quarto Document. Alternatively, use the button that looks like a blank page with a white “+” inside a green circle, and select Quarto Document. This will bring up a panel for creating a new quarto document:
On the left hand side we can see three options: Document, Presentation, and Interactive, and for each of these we can see there are different outputs. We can change these outputs later, but for now, select Document and HTML (this is the recommended format for working in). Give this document a title, something like “Basic About Page”. Before we create the document, we can see a couple of other options: Engine (leave this as Knitr), Editor (we will keep the visual editor box ticked), and then we can either click “Create” or “Create Empty Document”. For now, click on Create.
This creates and opens a new document for us to write in. We can note three things:
First, at the very top of our document is something called the YAML header. The YAML header is information about the document, and is always contained within two sets of three dashes. The YAML header sets things like the document title, subtitle, author, and the output file, as well as a lot of extra information. We will cover the YAML header in more detail shortly.
Second, we can see this document is not blank - it comes pre-populated with some information about Quarto and how to run code (if we don’t want to see this information, we could use the Create Empty Document button). These are often useful reminders when you are getting started, but once you are more familiar with Quarto you will delete these.
Third, this already looks like a document - that’s because we are currently in the “Visual” editor mode. We can click on the “Source” button to enter editor mode and see the markdown syntax.
You might also notice that within the YAML header there is a line selecting editor. While this says “visual” in both of the images above, we have manually over-ridden that with the inbuilt buttons in RStudio.
Exercise: Note three pieces of markdown syntax in the Source editor and how this translates into the Visual editor.
“##” - sets the Header level. Two # is “level 2”, three # is “level 3” (a smaller header). Note how these appear as headings in the Outline panel in RStudio.
“**” - when a word is surrounded by the double * it will become bold. Using a single * around a word will be interpreted as italics.
“<>” - are used to create a link. A word can also be embedded as a hyperlink by surrounding it with square brackets followed by the link itself in round brackets.
We will cover more syntax shortly. Almost anything you would like to do can be achieved and is covered on the Quarto website.
If ## designates a header, why isn’t this line coming up as a header? When you need to specify something like a # or an *, add \ (a backslash) first. This is known as ‘escaping’ and means that the next symbol will appear as-is in the document, rather than being translated as markdown.
Rendering a document
The RStudio visual editor has a built in button for rendering a document, which will simultaneously open up a Preview. The Preview can either be viewed in a new window or in a panel in RStudio.
Visual or Source Editor
When I started writing this workshop I was almost exclusively using the Source Editor. During the process of writing this workshop I became more familiar with some of the features of Visual and started using that as a preference. You can use one or the other, and we will try and demonstrate some of each.
The advantage to working in the Source Editor is that you are learning the markdown language. This is useful if you want to work on your documents while you are away from RStudio (for example, I often work in VisualStudioCode (VSCode), which doesn’t have the same visual editor).
The advantage to working in the Visual Editor is speed and convenience - you can use basic buttons to add bold or italic text, embed links, insert tables etc.,.
Exercise: Visual and Source (five minutes)
To start: in the quarto document highlight everything outside of the yaml header (everything below the bottom three dashes) and delete it.
Move to the Visual Editor, and use the toolbar buttons to:
Insert a piece of Bold font.
Insert a piece of italic font.
Select and highlight a piece of text (using the </> button).
Add a heading above these bits of text you have just created (using the drop-down button called Normal).
Add a numeric list with three different items on it.
Embed a link to yesterdays’ Github workshop: https://swcarpentry.github.io/git-novice/instructor/index.html (use the chain-link button).
Finally, insert an example table with column headers and some example text.
Once you have completed these tasks, switch back and forth between the Visual and Source Editor to see how these different effects are done with markdown.
As you can see, the Visual editor makes it much easier to work in the Quarto markdown language.
Other syntax options and notes:
We can also use superscript and subscript, by surrounding text with ^ or ~ respectively, and strikeout strikethrough text using double ~~ on either side of the word.
Paragraphs (and items in lists) need to be separated by an empty line. If there is no empty line between paragraphs, they will be interpreted as having a space between them.
If you are writing lists manually (i.e., not using the Visual editor option) you can either add unnumbered lists with an *, or you can add numbered lists with any number followed by a fullstop at the start of the line. Note that any number works (try writing a bullet point list with 1. 2. 2. 4. 5. to start each line, remembering to separate lines with an empty line). Quarto will automatically sort the numbers, which means you can number lists and then easily add additional points anywhere along the list.
YAML headers
At the top of each .qmd document we create, we will need a YAML header. YAML (Yet Another Markup Language or YAML Ain’t Markup Language) is placed at the very top of the document and is used to define the document metadata and output settings. For a single document, like we have here, we will provide all of our information in this YAML header. For a larger project like a book or webpage we will provide a separate document with global information and the individual page YAML headers will be minimal.
One thing to note about YAML headers: they are fussy. Information within the YAML header must be stored between two lines each containing three dashes. When providing arguments you must provide both parts of the key-value pair, must use nesting where appropriate, and you must pay attention to indentation.
Document metadata
Arguments are provided in key-value pairs with a specific format.
Title
title: "A grand yet succint paper title"
Note that technically you do not need to put the title itself in quotation marks, but you need them if you want to include things a colon (otherwise, the YAML header will attempt to interpret the colon).
Date
The basic format for date is:
date: 29-05-25
There are a lot of different formats we can use for date formats:
MM/dd/yyyy
MM-dd-yyyy
MM/dd/yy
MM-dd-yy
yyyy-MM-dd
dd MM yyyy
MM dd, yyyy
YYYY-MM-DDTHH:mm:ssZThese options have a hierarchy. That means that Quarto will attempt to interpret the date in the order of formats above. In practice, this means that
date: 05/06/2025
Will be interpreted as May 6th, 2025.
For the date:
date: 13/07/2025
Quarto will first attempt to read it as month/date/year, but since that doesn’t work it will be intepreted as “The 7th day, 13 months from the start of 2025” - January 7th, 2026.
For this reason I strongly recommend using one of two options:
date: today The current local date.
date: last-modified The last date the input file was modified.
What impact does this have on reproducibility?
It’s important to include this information in even our most basic documents. Clear authoring is required for fair attribution and for directing readers in terms of who to contact.
Using a last-modified date format helps the reader to understand the timeline of the file, such as what public data or software versions were available at the time of last render.
Output format
When we want to output our document as a single format we use the basic key-value pair:
format: html
We can easily change the format after rendering to create a new document which duplicates the format e.g., you could generate a slideshow and a static pdf/html as a backup (this is recommended if you might be presenting on a shared machine).
Exercise: Exploring revealjs
Add a new heading in the .qmd document (either set the line to Header 2 in Visual Editor or type two # symbols) and call it “Section 3”.
Change the format of the output from html to “revealjs” and render.
Explore the revealjs (slideshow) format.
Global code options
Code options included in the YAML header are global - they will be applied to all code cells in this document. As we will cover below, individual code cells (chunks or blocks of code) can be controlled separately. Some useful global options we might want to set in the YAML header are:
code-fold: true
code-tools: true
When code-fold is set to true, all code blocks will be automatically collapsed. This is useful when you want code to be available but would otherwise distract from the flow of the document e.g., when teaching/training, presenting at lab meetings. Code-tools provides a simple button at the top of the html that can then be used to toggle all code to open/closed (an easy ‘reset’ of all code blocks).
Useful features
There are other useful features we can control through the YAML header. Some examples:
toc: true will autogenerate a table of contents (for multi-page websites or documents).
bibliography: references.bib autogenerates a bibliography from a bib file.
csl: nature.csl sets the citation style.
number-sections: true adds auto-numbering for each section.
Summary
What have we covered?
Initiating a .qmd file.
The Visual and Source Editor windows.
An introduction to the qmd syntax: italics, bold, hyperlinks, headings.
The YAML header controls global options, such as author/date/document type metadata as well as a whole series of additional tools. If you are creating a single document (pdf, slideshow, standalone HTML) all of this information will be within the header at the top of the document. If you are creating a complex project (like the webpage you are reading now) most of that information will be stored in a separate document which we will cover later. As you will see below, you can over-ride the global options for certain blocks of code.