Quarto and Markdown

Packages in this module

Packages: tidyverse, quarto

Quarto

Once you have R, R Studio and Quarto installed, you are ready to start integrating text and code with Quarto. Quarto is an open source publishing platform that enables you to integrate text with code. If you have used R Markdown before then Quarto will look familiar to you because Quarto is the next generation of R Markdown.

RStudio comes with a version of Quarto already installed, but it can be useful to install the most recent version separately and because doing so will allow you to use Quarto with another IDE like VS Code. You can install the most recent version of Quarto by visiting this page and selecting the version for your operating system.

Now take a little time to create a Quarto project in R Studio and make sure everything is working properly. But before you get started, create a new folder(directory) for this course on your computer somewhere. Once that is done, go to File > New Project. Then select Quarto Project and name the project something like “test-project” in the Directory name field. Next, select Browse and navigate to the folder that you created for this course. Select Create Project.

You will notice that in your new project folder there is a file with an .Rproj extension. The .Rproj file is what tells RStudio which files are associated with the project and it obviates the need to set the working directory. It also makes it possible to share the folder with anyone who is running R and RStudio and have them run your code without having to set a working directory. This is what we refer to as a project-based workflow and we will use it for every assignment in this class.

Now try rendering the document with the Render toggle button. By default, Quarto renders an .html file that it will open in a browser and save to your project folder.

Next we want to try rendering a .pdf document. To do this, we have to install tinytex, a lightweight version of LaTeX. To do this, go to the Terminal and type quarto install tinytex. Now, change the format from html to pdf by inserting format: pdf in the YAML header. Then render the document again. A .pdf document should open up.

Now take a few minutes and try changing more of the code in the YAML header. You can try changing the title, adding a subtitle (subtitle:) or changing the execution options. By default, Quarto uses the visual editor but behind the scenes it is using Markdown. Try and edit some text using the toggle buttons available in the visual editor and then switch to Source to view the underlying Markdown code.

Markdown

You may already have some experience writing in Markdown, which is a lightweight markup language that enables you to format plaintext files. If you have not used Markdown, or if your memory is hazy, don’t worry: it is really easy to learn.

A Quarto document is made up of three basic elements: a YAML header (the part between the --- lines at the top, where you set the title, author, date and output format), Markdown content (your regular text, formatted with a few simple symbols), and code chunks (where the R code lives). Markdown governs everything outside the code chunks.

Here are the basics:

  • Headings are created with # symbols: one # is the largest heading (level 1), ## is the next size down (level 2), ### is level 3, and so on.
  • Emphasis: wrap text in a single asterisk for italics (*italics*) or two asterisks for bold (**bold**).
  • Lists: start a line with - for a bullet list, or 1. for a numbered list.
  • Links: [link text](url) — for example [Quarto](https://quarto.org/) becomes Quarto.
  • Images: same idea as links, with a ! in front — ![alt text](file path or url).
  • Code chunks: fence a chunk of R code with three backticks and a curly-brace language tag, e.g. ```{r} on its own line, your code, then ``` to close it. Chunks can be run one at a time from the editor or all together when you render.

Try editing some text in your Quarto document using these elements, then switch between the Source and Visual editors to see how each one is represented in the other. When you’re ready to see everything Markdown can do, have a look at this Markdown guide and this cheat sheet for quick reference.

Finally, take some time to get familiar with the Guide and Reference sections of the Quarto website. Then take a look at the gallery so that you can get an idea of the kinds of things you can produce with Quarto.