R Quarto Tutorial - How To Create Interactive Markdown Documents

R Quarto is a next-gen version of R Markdown. The best thing is - it's not limited to R programming language. It's also available in Python, Julia, and Observable. In this R Quarto tutorial, we'll stick with the most popular statistical language and create Markdown documents directly in RStudio. With Quarto, you can easily create high-quality articles, reports, presentations, PDFs, books, Word documents, ePubs, and even entire websites. For example, the entire <a href="https://jjallaire.github.io/hopr/" target="_blank" rel="noopener">Hands-On Programming with R</a> book by Garrett Grolemund is written in Quarto. Talk about scalability! We'll kick off today's article by installing and configuring Quarto, and then we'll dive into the good stuff. <blockquote>R Markdown and PowerPoint presentations? <a href="https://appsilon.com/r-markdown-powerpoint-presentation/" target="_blank" rel="noopener">Learn to create slideshows with R</a>.</blockquote> Table of contents: <ul><li><a href="#get-started">How to Get Started with R Quarto</a></li><li><a href="#basic-tutorial">Render Code, Tables, and Charts with R Quarto</a></li><li><a href="#export">How to Export R Quarto Documents</a></li><li><a href="#summary">Summary of R Quarto</a></li></ul> <hr /> <h2 id="get-started">How to Get Started with R Quarto</h2> First things first, head over to <a href="https://quarto.org/">their website</a> and hit the big blue "Get Started" button. You'll be presented with the following screen: <img class="size-full wp-image-13111" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d39e85b6bd7053b5f971_d70a3cad_1-4.webp" alt="Image 1 - Getting started with R Quarto" width="3398" height="2668" /> Image 1 - Getting started with R Quarto From there, download a CLI that matches your operating system - either Windows, Linux, or Mac. We're on macOS, and Quarto CLI downloads as a <code>.pkg</code> file which installs easily with a couple of mouse clicks. Once installed, launch RStudio (you can also use VSCode or any other text editor), and create a new text file, just as it's shown below: <img class="size-full wp-image-13113" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d3aa8457b5a5dc8bdb11_af7ba5d3_2-4.webp" alt="Image 2 - Creating a new text document in RStudio" width="388" height="886" /> Image 2 - Creating a new text document in RStudio <b>Important note:</b> Make sure to give the <code>.qmd</code> extension to the Quarto file. We've named ours <code>quarto.qmd</code>, for reference. Almost there! The final step is to install two R packages - <code>tidyverse</code> and <code>palmerpenguins</code>. Install them from the R console by running the following commands: <pre><code class="language-r">install.packages("tidyverse") install.packages("palmerpenguins")</code></pre> And that's it! You're ready to create your first R Quarto document. <h2 id="basic-tutorial">Render Code, Tables, and Charts with R Quarto</h2> As with any Markdown document, a good practice is to include a YAML header to provide some context around your document. The entire header has to be demarcated by three dashes (<code>---</code>) on both ends. The example below shows how to include the document title, author, and date to the YAML header of an R Quarto file: <pre><code class="language-markdown">--- title: "Quarto Demo" author: "Appsilon" date: "2022-5-24" ---</code></pre> Once you write yours, hit the "Render" button to preview the document. It's located in the toolbar just below the document name: <img class="size-full wp-image-13115" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d3ab02cd257900c8ba94_bc780a0b_3-4.webp" alt="Image 3 - Toolbar for rendering R Quarto documents" width="1050" height="152" /> Image 3 - Toolbar for rendering R Quarto documents Here's what the rendered document looks like on our end: <img class="size-full wp-image-13117" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d3ac8b19bf721420d649_615a6852_4-4.webp" alt="Image 4 - Rendered R Quarto document" width="1204" height="292" /> Image 4 - Rendered R Quarto document You can also check the "Render on Save" checkbox so you don't have to manually render the document each time you make a change. Optionally, you can also render Quarto documents through the R console: <pre><code class="language-r">install.packages("quarto") quarto::quarto_render("notebook.Rmd")</code></pre> We'll stick to the first option. Now it's time for the good stuff. We'll embed code snippets right into the Markdown documents to show the MTCars dataset, both as a table and as a chart. <h3>Render Table in Quarto</h3> First, let's add a new section and show the first six rows of the dataset by calling the <code>head()</code> function: <pre><code class="language-markdown">## MTCars Table below shows the first six rows from the MTCars dataset ```{r} head(mtcars) ```</code></pre> Here's what the document looks like after rerendering: <img class="size-full wp-image-13119" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d3adc2d0cc186c27f926_fefe636f_5-4.webp" alt="Image 5 - Rendered R Quarto document (2)" width="1848" height="1204" /> Image 5 - Rendered R Quarto document (2) Amazing! Both code and table are rendered with beautiful stylings. If you hover over the code block, you'll see an option to copy it with a single click. That feature is particularly useful for longer code snippets, and you don't have to lift a finger to implement it. <h3>Render Chart with Quarto</h3> Let's also see how to render a chart with Quarto. The procedure is identical - just add the code - but there are a couple of things you can tweak. First, it's a good practice to reference a figure. In Quarto, that's done by writing <code>@figure-name</code> in the text and then assigning labels to the figure in the code. The other good practice is to add a caption to your figures. Sure, you can add it directly through <code>ggplot2</code>, but adding it through Quarto will automatically match the text to document styles. Long story short, here's how to add a scatter plot to a Quarto document: <pre><code class="language-markdown">@fig-mtscatter shows a relationship between `wt` and `mpg` features in the MTCars dataset. ```{r} #| label: fig-mtscatter #| fig-cap: Weight of vehicle per 1000lbs (wt) vs. Miles/Gallon (mpg) <br>library(ggplot2) <br>ggplot(mtcars, aes(x = wt, y = mpg)) +    geom_point(color = "#0099f9", size = 5) ```</code></pre> And here's what it looks like when rendered: <img class="size-full wp-image-13121" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d3ae9bd3e45a218a884b_a7992b04_6-3.webp" alt="Image 6 - Rendered R Quarto document (3)" width="1624" height="1996" /> Image 6 - Rendered R Quarto document (3) <blockquote>Are you new to data visualization in R? <a href="https://appsilon.com/ggplot-scatter-plots/" target="_blank" rel="noopener">Here's a complete guide to scatter plots</a>.</blockquote> And that's how you can create a basic Quarto document! Next, let's see how you can export it. <h2 id="export">How to Export R Quarto Documents</h2> There are numerous ways of exporting Quarto documents. Some options include HTML, ePub, Open Office, Web, Word, and PDF. We'll show you have to work with the last two options, as these are the most common. First, let's address Microsoft Word. All you have to do is to add a couple of lines to the YAML header of the Markdown file. The example below shows how to add a table of contents with a custom title alongside some other options. <a href="https://quarto.org/docs/reference/formats/docx.html" target="_blank" rel="noopener">Here's a full reference manual</a>, if you're interested to learn more. <pre><code class="language-markdown">--- title: "Quarto Demo" author: "Appsilon" date: "2022-5-24" format:    docx:        toc: true        toc-depth: 2        toc-title: Table of contents        number-sections: true        highlight-style: github ---</code></pre> After rendering, the MS Word document will be opened automatically. It's also saved to the same directory where your <code>.qmd</code> document is located. Here's what it looks like on our end: <img class="size-full wp-image-13123" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b2ac2ac7e3060ed8cb1f6c_7-3.webp" alt="Image 7 - Rendered Word document" width="2280" height="2546" /> Image 7 - Rendered Word document It's read-only by default, but you can always duplicate it to make changes. Onto the PDF now. Before starting, you'll need to install a distribution of TeX. TinyTeX is recommended by Quarto authors, so that's what we'll use. Run this line from the shell: <pre><code class="language-bash">quarto tools install tinytex</code></pre> Once installed, modify the YAML header accordingly. <a href="https://quarto.org/docs/reference/formats/pdf.html" target="_blank" rel="noopener">Here's an entire formatting reference</a>. <pre><code class="language-markdown">--- title: "Quarto Demo" author: "Appsilon" date: "2022-5-24" format:    pdf:        toc: true        toc-depth: 2        toc-title: Table of contents        number-sections: true        highlight-style: github ---</code></pre> As you can see, the only change you had to do is to replace <code>docx</code> with <code>pdf</code> - all arguments are identical. Here's what the document looks like: <img class="size-full wp-image-13125" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b2acae0726c5370e6213c7_8-3.webp" alt="Image 8 - Rendered PDF document" width="2486" height="2596" /> Image 8 - Rendered PDF document And that's how you can export R Quarto Markdown files to Word and PDF documents. As mentioned, other options are available, but we won't cover them today. <hr /> <h2 id="summary">Summing up the R Quarto tutorial</h2> Today you've learned the basics of creating highly-customizable Markdown documents in R Quarto. The package is a breeze to work with, and the documentation is easy to get around with. If you're developing packages for R, Python, or Julia, there's no reason not to use Quarto to create amazing documentation around your product. It's much more capable than other alternatives, and also has all the exporting options you'll need. <blockquote>Thinking about a career in R and R Shiny? <a href="https://appsilon.com/how-to-start-a-career-as-an-r-shiny-developer/" target="_blank" rel="noopener">Here's everything you need to know to land your first job</a>.</blockquote> If you decide to give R Quarto a try, make sure to let us know. Share your Markdown documents with us on Twitter - <a href="https://twitter.com/appsilon" target="_blank" rel="noopener">@appsilon</a>. We'd love to see what you come up with.