Get started with Quarto | Mine Çetinkaya-Rundel
This video walks you through creating documents, presentations, and websites and publishing with Quarto. The video features authoring Quarto documents with executable R code chunks using the RStudio Visual Editor (https://quarto.org/docs/visual-editor/). 00:00 Introduction 00:34 Authoring a document with Quarto 01:13 Using the RStudio visual editor 04:13 Code chunks and chunk options 06:31 Inserting cross references to figures and tables (https://quarto.org/docs/authoring/cross-references.html) 08:56 Adding a citation from a DOI (https://quarto.org/docs/visual-editor/technical.html#citations) 10:10 Seamlessly switching between output formats 10:58 Creating Quarto presentations (https://quarto.org/docs/presentations/) 14:36 Customizing the output location of code in presentations (https://quarto.org/docs/presentations/revealjs/#output-location) 16:09 Creating a website from scratch (https://quarto.org/docs/websites/) 19:19 Creating multi-format documents (https://quarto.org/docs/output-formats/html-multi-format.html) 20:22 Publishing the website to QuartoPub (https://quarto.org/docs/publishing/quarto-pub.html)
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hi, my name is Mina Çetinkaya-Rundel and I am a developer educator at Posit as well as a professor of the practice at Duke University. And in this video, I'd like to introduce you to Quarto. So if you've been hearing a lot about Quarto and wanting to dive in and sort of have been waiting to see when is the right time for me, or if you've played with it a little bit and want to get a sense of what more it can do and what more you can do with it, hopefully this will be a good introduction for you.
Authoring a document with Quarto
So we are going to start things pretty simply. We're going to start with a single Quarto document. I am going to open that up in RStudio. My Quarto document is called index.qmd. For those of you who are familiar with R Markdown, you're probably familiar with file suffixes called RMD and Quarto documents are called QMD. At the top of this document, things should look pretty familiar. We have a YAML with some metadata about our document, a title, the format that we want to output to. So we're going to make an HTML document first.
Using the RStudio visual editor
And I'm going to use the RStudio visual editor. So again, if you are familiar with R Markdown and haven't played with RStudio visual editor lately, you can switch over to the source editor and things should look pretty familiar to you. But let's go back to the visual editor where you get a document that feels a bit more like Google Docs or writing in an app like Notion where things are a little bit more what you see is what you get. For example, I have some information about the dataset I'm going to use here, the penguins dataset from the Palmer penguins package, and I might want to bold the name of the package and I can do that by using the toolbar here, or I can use keyboard shortcuts to do that as well.
The visual editor has other handy tools on the toolbar. For example, I can directly add a link to this. So let's go ahead and add a link to the Palmer penguins website and hit OK. So that now is a live link. And if we were to switch over back to the source editor, if you are familiar with writing things in Markdown, you can see that under the hood, it is writing the Markdown for you. It's just that you are not the one having to write the Markdown. So let's go ahead and render this document and let's see what it looks like.
A setting that I like to use on my RStudio IDE is I generally like to preview my documents in the viewer pane so that I can see my source code on one side and my rendered document on the other side. So we should be able to see our rendered documents here in the viewer pane on the right hand side of our RStudio IDE. Things will look pretty similar between the source document and the rendered document because our source document is also using this visual format. But the difference is that on the source side, we only have the code and on the output side, we're seeing the code and the output to go along with it.
Code chunks and chunk options
So let's introduce you to a few of Quarto's features now. We can see that we are taking a look at the Palmer Penguins dataset and we have a visualization here for it, but we might want to take a look at the actual data itself. So I am going to go ahead and insert a code chunk here, which I can do either with the insert code chunk menu here, or using my keyboard shortcut with the forward slash and bringing up the insert to anything toolbar. I'll say I want an R code chunk. Let's say that I want to glimpse at the Penguins dataset.
Let's go ahead and render that document and we'll be able to see the input and the output on the viewer side. Scrolling down on this document, I have a code chunk that generates a plot. So one thing that I might want to do is add an alternative text to this figure, for example, and I can do that by using the fake out chunk option. The visual editor nicely does YAML completion for me, so I can choose from here which chunk option I want to use. I'm going to go with fake out and I have a multi-line chunk option. So I'm going to use this vertical bar here. I've already written the out text, so I will just copy and paste that here. So you don't have to watch me type this out, but basically we're saying that this is a scatter plot of Penguins bill depth and length, colored by species. And we say something about the trend we see. It's relatively strong and a linear association.
Let's go ahead and render this document. And when we render the document, the alternative text won't show on the output because again, it's not part of the output necessarily, but the underlying source code. But if I pop this out to a browser window and scroll down to my figure and right click on it to inspect it, I should be able to see that the out text is actually available for me under the hood.
If I'm writing a report, I might want to not necessarily show all of this code on the output. So one thing I can do is I can hide the code one chunk at a time with another chunk option, echo false. And that will only hide that particular chunk option, that particular code chunk's code. But if I want to do that at the document level, I have a few options as well. I can actually go to the YAML on top of my document and under execute, say I want to do echo false. And let's go ahead and render this full document. And we will see that all of the code is now hidden and we only have the output, which might be preferable for you depending on your audience, whether you want them to see the code or not. And here we go. Here's our output without any of the code.
Inserting cross references to figures and tables
Over here, we have a figure that's being generated with code. And in the text, I have said the figure below is a bar — is actually a scatterplot. Let's go ahead and pull up that scatterplot of species of penguins. We can add cross references to this. So in order to add a cross reference, I need to do two things. First, I need to change my chunk label to include the word fig at the beginning as a suffix. So that's fig dash. And second, I need to add a caption. So to add a caption, I will use the fig cap. And maybe let's go ahead and reuse this information from here. All right, so now I have a figure that has a label that starts with fig and a caption.
All right, so let's highlight this. And let's say we want to insert a cross reference. The figure is available for me to choose here. And if I render the document one more time, it will create a link to the figure itself. So now I don't need to worry about when I render my document if it's below or above, particularly if I'm outputting to something like PDF.
I can do the same thing with tables as well. The only difference is that I would need to add the TBL for table suffix. And similarly, I need to add a caption for that too. So this will be, um, let's say the first 10 penguins.
And let's go ahead and do this without using the insert menu. I can simply grab the label and I can say instead of the table below at and the name of my table, and I can render my document and it will do the counting and the labeling of my figures for figures and tables for me. So I have a figure one here, um, and then a table that's going to be cross-referenced underneath it as well. And here we go. We also have a table one.
Adding a citation from a DOI
The last thing I'd like to show in the visual editor is adding citations, which can be a huge hassle sometimes. So here we are going to cite where these data come from. So in order to do that, I'm going to say, I want to insert a citation and you can see that I have some options to choose from in terms of where my citations can come, but I am going to go ahead and grab the DOI of the paper where the Palmer penguins data were originally published. And I can say that I want to insert this. And when I do so two things happen, uh, reference gets added, gets added here. And you can see that my YAML already also gained a new line called bibliography. And if I go to my files, I have actually gained a file called references.bib. And in this file is the sort of the bib reference for this paper.
So if we go ahead and render this document, we will see that the reference has been added. If I hover over it, I can see it. Or if I click on it, it will take me to the end of my document where I have a section called references inserted for me.
The last thing I'd like to show in the visual editor is adding citations, which can be a huge hassle sometimes.
Changing output formats
So we've talked about creating a single document with Quarto. Um, and this has been a HTML document so far. If I want to change the output to something like a PDF, all I need to do is indicate that on my YAML. So let's go ahead and give that a render too.
I don't need to change anything in terms of the syntax in my document, right? Now we have a PDF document with the same content also hiding the code. Um, so respecting the YAML options that we had, um, indicated earlier. And the nice thing about this PDF document is not only, um, did I, was I able to obtain it so easily, but it also shows up in my viewer tab as opposed to a pop-up window.
Now let's go ahead and change things up even more. We've gone from a single HTML document to a single PDF document. What about making slides? So I'm going to make HTML based slides using revealjs as my output. And once again, I am not going to touch anything in my document. The only thing RStudio asks me to do is to reload the visual editor when I change the output format. And let's go ahead and render that as well. And here we go. Our document title is now a title slide. I can actually scroll through the different slides that I have. Each of them are sort of determined by these headings.
Building a slide deck
Um, so let's go ahead and actually turn this into a slightly more reasonable slide deck. Now things worked, but my text is a little bit squished. Um, I am going to take a look at the, um, outline, um, view here where I can see the different sections in my document.
Um, and I'm going to make these my, uh, second level headings. So these, uh, particular data species and penguins are going to be second level headings. And let's go ahead and insert some first level headings as well. Using the insert anything tool, we'll say that I want a first level heading. Maybe first I want something like introduction. And then at the end, I might want something like, um, analysis and maybe a slide here, something like modeling results. And then I might finally want another slide, um, at the end called references. Remember those references that I had, I might want to move them to the very end. So I've created this structure, hierarchical structure for my document that I can nicely view here in the outline.
And if I render my document, I should be able to see that that same, um, outline is, um, apparent in my slide deck as well. My first level headings are going to turn into section dividers in my slides. And then my second level headings are going to turn into, um, sort of indicators for a new slide. So we can see that same outline here, and I can go ahead and scroll through my slides.
Um, some things that I'm seeing here for this data slide, things look a little too big. Maybe things are not filling in. So using the visual editor, I can start tweaking things. I can write full on CSS for my slides, but I can also use some of the predefined classes. So one of my favorite is the smaller class, for example. So let's go ahead and do that and render that. And that should squish my text, make it a little bit smaller, allowing me to fit a bit more text into my slides. Never a great idea to put a lot of text on your slides, but if you're in a pinch and you just want things to be a little bit smaller so everything fits, this is a really nice fix.
Um, let's also go ahead and say that I do want the, um, code to be shown. So I'm going to say echo true. So say I'm teaching and I actually want to show the code as well. We'll see that our slides get busy again because we have both the code and the output on one slide. This one looks pretty fine, but over here we're seeing that, um, the figure is squished in order to make room for the code. Well, we have a remedy for that as well.
Um, what I'm going to say is for this particular slide, uh, and this code chunk, I want the output location to be, let's say column fragment and see what that, uh, gets us. So what this is going to do is put my code in one column of my slides and my output in the other column of my slides, but it will actually, um, add some, um, sort of animation to my slides and delay the output. So I might get something like this where when I move to the next slide, I can see the code. This still looks pretty squished. So if I don't want that, I can choose a different option. Once again, using the YAML completion with my tab and I might say, okay, just move it to the next slide for me. So the plot moves to the next slide.
Building a website
Um, so we've made a single document so far and we have made, um, also a, um, a slide deck. Now let's imagine a situation where you have multiple documents, a project, and you want to put them all together in something like a website. So what we're going to do is let's go back and change the format to HTML again, reload our visual editor, and render this document as a single HTML document.
And let's go ahead and add one more document, maybe something that says about — something like an about page for our webpage. I'm going to create a new document called about, probably has some boilerplate language here. Maybe let's go ahead and select all of that and delete it and say, this is a demo website. And I'm going to save this file as about.qmd.
And now I have two documents, two qmd documents in my project — about.qmd and an index.qmd. And I have their outputs as well. Let's go ahead and clear those out, those outputs so that I have just my source files here. To bring these two together in a website format, I just need one file, a plain text file called, um, specifically called underscore Quarto.yml. And in here, I need to actually tell Quarto how to bring things together.
So I want a Quarto project. I want the type of this project to be website. Note that I'm not even typing these. I'm using the YAML completion. And in this website, I want the title of my, um, website to be perhaps welcome to Quarto. And I want a nav bar. Let's say that on the left, I would like to link, link to my index.qmd file and my about.qmd file.
And let's go ahead and save this. And I am going to just relaunch this, uh, project from the project navigator in RStudio. And once I relaunched this project, we can see that I gained a new tab called builds. And let's go ahead in this new build tab, click on render website. And voila, I have a website. Let's pop this out to a browser window so we can see things a little bit more nicely. I can see that on top, I have a navigation bar with my two pages, my hello penguins page with my analysis page. And I can see that I have a navigation bar with my two pages, my hello penguins page with my analysis and also my about page. Um, and they're automatically linked to that and basically clicking on the name of the website takes me back to my homepage.
Um, let me show you one other, uh, feature. That's actually a newer feature of, uh, Quarto starting with 1.3. Let's go ahead and for this index page, add another format. So I am going to say that I do want an HTML, uh, with default options, but I also want a PDF, um, of the same document as well. And let's go ahead and render the website one more time. And if I take a look at my output now, we can see that not only do I have the HTML file on my website, but I have an ability to actually download a PDF version of my document. So if you are sort of, uh, creating websites, but you have artifacts in there that you would like people to be able to download as PDFs, um, I think this is a really handy tool for doing stuff.
Publishing with Quarto Pub
So we've gone from a single document to a slide deck to a website, but all of this is living on my computer. To wrap things up, let's talk about how do I get this and make it available to others. Obviously I could use version control, take, get things to, uh, GitHub and publish from there. But another option is to use, uh, Quarto pub. So I am going to now go to my terminal and in my terminal, I am going to type, uh, Quarto publish.
And when I hit Quarto publish, it gives me some, uh, options for where I might want to publish. I'll say that I want to publish to Quarto pub. I have previously linked my account here. So if this is your first time doing it, it's going to ask you to actually create and link an account. But yes, I do want to, um, and I do want to authorize this.
The site name comes from the name that I gave it in my Quarto file. So that was welcome to Quarto. And as simply created, I'm going to give it a name. So I'm going to give it a name of Welcome to Quarto. And as simply created a sort of a version of it without spaces, and I'm going to hit enter, and we can see that it's rendering my page one more time. And it is now, um, shooting this, uh, once it's rendered, uh, publishing it on Quarto pub.
All right. And here we go. We can actually see that my page has been published on Quarto pub. Uh, this is the view for me to manage the site. I can delete the site for example, or change its slug if I want, but I can also, I'm also provided a direct link to it that I can share with others. So I have, uh, the simple website that I have created with the two pages now published on the web and ready to share with others.
So I have, uh, the simple website that I have created with the two pages now published on the web and ready to share with others.
I hope you found this introduction useful. Um, and what I will do at the end of this is, uh, commit and push all of my changes to a GitHub repository where you can simply, uh, pick things up from where I left off and continue, um, your exploration of Quarto.
