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. We 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.

We won’t need this beyond today, so you can call it something like my-test-repo if you like. 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. Click Create Project

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:

New Quarto doc panel

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.

Visual Editor mode is active

Source Editor mode is active

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: Syntax (2 min)

Note three pieces of markdown syntax in the Source editor and how this translates into the Visual editor.

  1. ## - 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.

  2. ** - when a word is surrounded by the double * it will become bold. Using a single * around a word will be interpreted as italics.

  3. <> - 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 i.e., [this is the link text](https://this-is-the-URL.com)

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, and this workshop itself is written in Quarto, then why isn’t the line above coming up as a header?

Good catch! We have done something extra here called ‘escaping’. When you need to specify a character like a # or an * that is used for special syntax, you can add a \ (a backslash) first. This means that the next symbol will appear as-is in the document, rather than being translated as markdown.


Visual or Source Editor

You may chose to almost exclusively use the Source Editor, which has the advantage of helping you learn the markdown language. This is useful if you want to work on your documents while you are away from RStudio (for example, Visual Studio Code (VSCode) is a popular tool, which we are using to write this workshop, and it doesn’t have the same visual editor).

You may prefer to use the Visual Editor, which has the advantage of speed and convenience - you can use basic buttons to add bold or italic text, embed links, insert tables etc.,.

Today you can use one or the other, and we will try and demonstrate some of each.

Exercise: Visual and Source Editors (5 min)

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 to chose Header levels).

  • Add a numeric list with three different items on it.

  • Embed a link to the GitHub repo for this workshop: https://github.com/GenomicsAotearoa/reproducibility_with_git_and_quarto (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.

Other syntax options and notes:

We can also use superscript and subscript, by surrounding text with ^ or ~ respectively, and strikeout text using double ~~ on either side of the word.

Markdown Syntax Visual Output
super^script^ superscript
sub~script~ subscript
~~strikeout~~ strikeout

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 asterisk * or a hypen - or you can add numbered lists with any number followed by a fullstop at the start of the line.

Hints:
  • Note that any number works (try writing a bullet point list with 1. 2. 2. 4. 5. to start each line!). Quarto will automatically sort the numbers, which means you can number lists and then easily add additional points anywhere along the list.
  • Sometimes an ‘Enter’ or ‘Return’ to make a new line is not enough. You may also need to add two spaces at the end of the top line, if the subsequent line is appearing on the preceding.

Save and Render document

Save your Quarto file (CTRL + S or CMD + S), give it a name if you have not already (e.g., getting-started.qmd) and save it into the directory you made earlier (mine is called my-test-repo).

Now back in RStudio, click the ‘Render’ button, which will simultaneously open up a Preview. You can change the Preview settings by clicking the settings button next to the Render button. The Preview can either be viewed in a new window or in a panel in RStudio.

Alternatively, you can preview and render a document on the command line (e.g., in terminal in RStudio, type):

quarto preview getting-started.qmd

This should also open a Preview window automatically in your browser.

As you make changes on your .qmd file, every time you save the document the Preview will update.

Hit CTRL + C back in terminal to exit preview mode.

Note: quarto preview is great for live viewing, but we always need to generate our final output with quarto render. More on rendering later in this workshop!

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 do need them if you want to include things like a colon (otherwise, the YAML header will attempt to interpret the colon).

Author

To list an author on the document, we use the following key-value pair:

author: Barbara McClintock

Add your own name as the author of the document, render or preview the document and confirm it has worked.

There are two ways for this to work, and more ways for it to fail.

One way to add authors is to include them on the same line, separated by commas:

author: Barbara McClintock, Marie Curie

Note that in this case, while we can read them as separate authors, it would be more accurate to call this a single author with a long and confusing name.

The correct way to include multiple authors is to list each author on a separate line under author, with each line starting with a dash:

author:

- Barbara McClintock

- Marie Curie

This is an example of nesting, where we are providing multiple input sources under a single key. If we break the format (e.g., by having author: name on one line and -name on the next line) we will get an error message and the document will not render. This is a good demonstration of how YAML headers can be fussy.

You can also list multiple authors within [], with each author separated by commas:

author: [Barbara McClintock, Marie Curie]

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:ssZ

These 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.

Click save, and watch your Preview update.

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

Quarto can also render your documents into PDF, but you will need to first install LaTeX, if you do not already have it.

In r, you can install TinyTeX:

install.packages("tinytex")
tinytex::install_tinytex()

Or you can install full distribution like TeX Live (Linux), MacTeX (Mac), MikTeX (Windows).

Then you can set your YAML header to format: pdf and click render.

Exercise: Exploring revealjs (2 min)

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”. Add in more sections if you like!

Change the format of the output from html to revealjs and render.

Explore the revealjs (slideshow) format! 🤠

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.

… and many more!

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 formatting tools.

  • Creating a single output document (pdf, slideshow, standalone HTML) from the YAML header.