Welcome to Quarto Workshop! | Led by Tom Mock, RStudio

Transcript#

This transcript was generated automatically and may contain errors.

Hi friends! Thank you so much for joining. It's so nice to see so many of you at the RStudio conference, whether in person or virtually on the Discord too. Welcome to the RStudio Enterprise Community Meetup. I'm Rachel, calling in from Boston today. We are streaming out to YouTube Live today, so if you've just joined now, feel free to say hi through the chat window and maybe where you're calling in from.

I'm so happy to have my friend Tom Mock here with me today to teach us about Quarto . I know we've heard a lot about it lately on Twitter and LinkedIn and the RStudio conference, so I've been excited for this. Welcome to Quarto Workshop. If this is your first time joining one of these sessions, this is a friendly and open meetup environment for teams to share use cases, teach lessons learned, and just meet each other and ask questions. Together, we're all dedicated to making this an inclusive and open environment for everyone, no matter your experience, industry, or background.

I will be sure to share a link in the chat where you can also find out about other upcoming events too. We have meetups like this every Tuesday at noon Eastern time, and also data science hangouts every Thursday at noon Eastern time. This is our first two-hour workshop in this meetup environment, so thank you, Tom, for being the first here. During the event, you will be able to ask anonymous questions as well through our Slido link, which we'll share in the chat too. And we can also try and answer these in a follow-up blog post as well.

While we want to help with as many questions as possible, we likely won't be able to stop during the workshop to answer as many questions with so many people on today. But I'd recommend also asking follow-up questions after the event on community.rstudio.com. Curtis from our team just made a Quarto tag there as well. With all of that said, thank you so much, Tom, for getting us all started with Quarto today.

Awesome. Thanks, Rachel, for hosting and for helping with getting this all off the ground. I'm going to try screen sharing my screen once, and then we can always flop over to the presentation if we need to. Today is going to be a bit longer, so as Rachel mentioned, it will look a little bit different in terms of the format that you may have been used to. We're going to cover quite a bit of material, and so a lot of this is kind of getting people excited about Quarto, giving you some of the overview of what Quarto provides, but I've seen two hours, while that seems like a long time, we're not able to cover everything, so we're going to make this part of a longer series, and if you want to come and join us later on, we're also going to do things like creating a Quarto blog, or creating Quarto presentations, or one very specifically focused purely on Python as opposed to today, which will be mostly focused on R with a mix of Python in it.

For today's slides, we're going to go to a link, and we'll share it here in the chat real quickly, but this is the material for today. This website will be up forever, so you can always reference this material in the future. There will be an RStudio Cloud link as well as a place where you can actually download it locally, or clone a GitHub repository into your local RStudio, but for today, if you didn't want to install anything, you just wanted to get off the ground as fast as possible, you could always go into RStudio Cloud that's linked there as the third item.

I'll zoom in a little bit here just so that it's a little bit bigger when we're going through, but let me know if you have any trouble seeing it in the comments. So, to orient you on this slide, or kind of this website, if you go to the left, it says workshop, intro to Quarto, and authoring Quarto. The intro to Quarto slide will be our first section, and we're going to jump directly into that, and kind of give you this broad overview of what Quarto looks like.

So, thank you for joining, and again, we'll be posting some of the links in the chat, so I'll do my best to kind of re-emphasize that. Also, though, that these slides are already public, and if you look at the bottom of any of the slides, it will link back out to that website. So, if you see a screenshot of this, or want to take a screenshot, it actually has the URL built into each slide. So, let's get started, and we'll go into the presentation. So, for the first slide, we're going to say, hello, Quarto. So, welcome. We're using Quarto. We're going to be talking all about that today. Hopefully, you're in the right place here, and we're going to be going through quite a bit of the syntax and everything else.

So, we can go on and go to the next slide. Kind of our assumptions for today is that, you know, a little bit about R, you probably know a little bit about Markdown, but you're really here to learn about Quarto, and maybe you're learning about it for the first time, or maybe you're learning about it as an extension, or the next generation of R Markdown. If we advance the slide one more time, we can see that we'll be teaching you Quarto syntax, and Quarto formats, and more Markdown, and even more R along the way. So, while you might learn a little bit of R today, we're really focused on that Markdown, Quarto syntax, the formats, and how you can create them.

And we can continue forward. If you want to follow me, you can go to follow me on Twitter, or GitHub, or go to my blog, but really, you want to go to quarto.org as the primary resource for everything you want to learn about RStudio.

So rather than relying on literal R code and having a mandatory kind of R runtime to execute these documents, by moving the pre-processing onto Pandoc and providing Lua filters and other pre-processing outside of a single language, we can actually go beyond Knitter and use things like Julia natively, or use Python natively, or even JavaScript or other languages.

So let's advance to the next slide. When we talk about this being more than just Knitter, and we talk about things like Python and talk about Julia, we're just replacing one component. We're exchanging maybe R code for Python code or R code for Julia code, and then executing them natively via the Jupyter engine. You might be familiar with Jupyter as like an IPython notebook. In this case, we're really thinking of it as almost like a headless process, or a kernel that's executing the code, as opposed to it being the interface that we're using for our Quarto document. But your .qmd could be almost identical. All you're really doing is changing out the code steps. All of your markdown and Quarto syntax would be the same, and you'd just be changing out the language model. So allowing us to extend to more than just Knitter and more than just R.

We can advance to the next slide and see that, you know, while you might want to use a plain text format like a .qmd, you know, you're familiar with R markdown, and that's what you want to use, other teams might actually want to use a Jupyter notebook as their literal interface. So any of the languages that you can execute with Jupyter, we've focused really on Python and Julia inside Jupyter, but any of the languages you can execute in Jupyter can then be, again, converted to this markdown, rendered with Pandoc and Lua filters, out to your final report presentation and project.

So ultimately what these diagrams are telling us is that regardless of kind of the language, your kind of structure and how it actually happens behind the scenes is very similar, and it's really allowing us to have a shared syntax and a shared format across languages and across kind of input formats. This is expanded upon in the next slide where we talk about this in a bit more verbose terms. So just in case you miss the diagram or you want to kind of have it written out, Quarto uses an engine like Knitter to execute code and generate that temporary output or a .md file. The md file is processed via Pandoc and Quarto's Lua filters along with things like bootstrap CSS for HTML or LaTeX for PDF and then converted to the final output format depending upon what you chose.

Importantly, while the Quarto teams provided a lot of different Lua filters and pre-processing steps, other developers in other languages, whether they're written in R or Python or Julia, can also be applied and in most situations are interchangeable between formats and not language specific. So you can write a Lua filter that comes from someone developing a Python that helps out there are developers that are working in R and vice versa. So by moving the pre-processing into Quarto and into kind of the Pandoc native Lua filter, we're again getting more interchange and not requiring one language to do it one way.

Observable.js and client-side interactivity

The other benefit about what Quarto provides is, yes, Quarto can support HTML widgets in R and Jupyter widgets for Python and Julia and this allows you to have client-side interactivity for your documents. Beyond that though, it also allows you to use native JavaScript. So we have built-in support for Observable.js, which is a set of enhancements to vanilla JavaScript. It's by the same team, Mike Bostock, who authored D3 and there's actually some D3 integration directly into Observable.js.

So Observable is really powerful because it has essentially a reactive runtime, so it's well suited for interactive data exploration and analysis. Reactive runtimes are things like Shiny code, you know, that's another implementation of reactivity in R. We have reactivity here in JavaScript that's occurring only on the client side. So here we have an embedded Observable kind of little bar. If you go in there and you adjust the temperature, we can switch from say 34 degrees to maybe it's a bit cooler, a bit warmer, and we get this real-time execution of this code only on the client side. So I don't have a server running to execute this, this is all being done in the browser and you can get this real-time changes that you're seeing. So you can almost write your own HTML widgets on the fly with Observable that's baked into Quarto.

If we actually advance and look at what the code looks like, it looks a little bit different. Yeah, it's some JavaScript, but we're executing this in an Observable JavaScript chunk, but it's going to feel, again, very similar to writing code that you might have done with say something like Shiny. And you can have it interact with Shiny or go even further, but allowing you to do this without having to require a client side, or sorry, a server behind it.

Now, while this kind of interaction is cool, we're probably a bit more interested in something like graphics or kind of reactive graphics. So on the next slide, we actually have some graphics and then a widget that we can interact with it. And again, this is done all through Quarto via the help of Observable.js. So if we click on the dream tag underneath islands at the top right, we can actually add in new data back to this. So now for this penguin dataset, we actually have all the different penguins available here across all the different islands, and then we can adjust the bill length and get real-time changes that are observed inside the graphics itself. So whether you're working in R or Python or JavaScript or anywhere else, you have this ability to mix and merge between the different languages and have things interact and have all this client-side interactivity.

Quarto as a shared publishing universe

So this really means that Quarto is a big universe. It's not just R anymore. You know, it's not just Python or just Julia. It's really thinking about how do we serve all these different communities and bring in things that you might not have even thought about in terms of there's a lot of power in things like JavaScript and Observable that are also useful to use in your data science products. Ultimately, Quarto is kind of the part here in the middle that's providing this structure of allowing you to use R and Python and Julia and Observable together and create very complex and beautiful documents at the end.

So rather than thinking about, okay, I wrote my stuff in R and I wrote my stuff in Python and I have to generate a website and then I have to go generate a Word document and I have to redo all my work, by working through Quarto, you can essentially have some of this single-source publishing and have the ability to generate documents and websites and presentations all through this shared syntax, regardless of the language you're working in.

So rather than thinking about, okay, I wrote my stuff in R and I wrote my stuff in Python and I have to generate a website and then I have to go generate a Word document and I have to redo all my work, by working through Quarto, you can essentially have some of this single-source publishing and have the ability to generate documents and websites and presentations all through this shared syntax, regardless of the language you're working in.

On the next slide, we talk a little bit more about what Quarto actually is. You know, I've talked about all these exciting things, but what is Quarto in terms of breaking it down? Quarto itself is a command-line interface. So rather than, again, being just an R package or just a Python package or library, it's a language-agnostic command-line interface. So you don't even need any language on your computer to install it. You could just install it as a terminal, at your terminal, as a command-line interface and just use whatever language you want and add on to it.

If we click through a little bit to see what the next part is, we can actually execute a little bit of the code. So we can step through and see the version. So if we click the right arrow button, we can see that you can call things like Quarto help at the terminal or you can go through and see the different help. That's how I'm displaying the text here. I can also do things like Quarto render to actually render out my document or Quarto preview, which allows me to preview the document and maintain a background server so that as changes are made, I can actually see those live and have a real-time feedback as I'm writing my documents.

Quarto across editors: RStudio, VS Code, and Jupyter

What this really means in terms of Quarto being a command-line interface is it's not tied into one tool. Obviously, I love using RStudio and that's what I'm going to be showing a lot of today. So I can advance and see that, yeah, here's RStudio. It might be a little bit small for you to read everything, but it's going to feel very similar in a great way as your experience with Markdown and with RMarkdown . There's a lot of enhancements that Quarto provides on top of it, but you don't have to relearn the wheel just to use it. However, if you go to your colleagues and they say, well, I've never used RStudio. I'm not familiar with that. I use this other tool. Maybe they prefer something like a Jupyter Notebook or JupyterLab. You can also use Quarto as a command-line interface in Jupyter or with JupyterLab. So you can actually write literal .ipython notebooks and then render those out to Quarto documents as well. So you're not limited just to the RStudio interface. And for certain other people, they're like, well, I kind of like notebooks, but I don't want to write in Jupyter for some reason. They're choosing a different interface. You can also use VS Code. And this way, regardless of what kind of editor you're using, you're able to meet in the middle and collaborate with your colleagues and say, I'm using Quarto, you're using Quarto, but you're not limited to one interface or one language.

This kind of comes out a lot of times with the customers that I'm working with. And if we think about the different interfaces, this aligns with a lot of the most common open-source interfaces. And again, building on this idea of not just limiting it to one language or one editor, but trying to create something that's bigger than just RStudio. It's providing value for other communities besides just the R community.

Now, that being said, we obviously have spent a lot of time building Quarto into these different tools and enhancing them as much as possible. So you can actually, inside RStudio, have the visual editor mode. What this allows you to do is actually get real-time conversion of just the markdown and some of the CSS and see what that looks like. So rather than only looking at the plain text or only looking at the rendered output once you've kind of finalized your document, with the visual mode, you can actually see, again, in literal real-time, the conversion of markdown or LaTeX or CSS, or even creating tables and graphics, what they look like inside the body of the document. So a lot of power here to not only write your documents, but have a better writing experience. So there's even things like adding bold text or inserting tables or graphics built into the editor and allowing you to have this rich experience inside RStudio.

Again, you'll want to be on the latest version, 2022.07.1 of RStudio, provides all these integrations. And while you can use Quarto in older versions of RStudio, some of the enhancements came at this most recent version from RStudio Conf.

Now, to explore what the visual editor looks like, we actually have a workshop material. So underneath the O3 authoring visual editor, there's the ability to kind of go through the visual editor mode. And you can click around and see some of these things and how they look like. So includes things like citations or the UI elements, as well as the visual editing mode. And you can turn it on and off to explore the sections.

So going on to talk a little bit about the other editors. Again, we don't want to just limit these enhancements to something like RStudio. We want them to have a really good experience in any editor. So again, you're not limited to RStudio, but there's a lot of power there. If you are coming from, say, the VS Code world or that's the tool you want to use, there's a VS Code extension that allows you to get both the syntax highlighting and some of the auto completion and YAML linting and other things built into VS Code. And when you render something, you get it in this little pop-up page and have the side-by-side experience that you're familiar with.

This also applies to things like YAML. So if you've used IPython notebooks, you may not write YAML in them because the IPython notebook or the Jupyter notebook doesn't really care about the YAML. It doesn't change what the Jupyter notebook does, but it's really important for Quarto. So you can write these as a raw chunk in a Jupyter notebook. And again, you can use Jupyter lab as your interface. You're not limited to a plain text format, although I really like plain text formats like .qmd. You can, again, use an IPython notebook as your kind of editor of choice if that's the way you want it to go.

We also have YAML intelligence. So this is obviously built into RStudio, but also within VS Code, it has auto completion through the VS Code extension for things like different YAML options. So not only would it help you find out what are the options you can change, but it'll help you define them and then input them, as well as the outputs you can do for them. So here for theme, we might start typing th, and then we can auto tab complete to theme, and then it'll let us see that we have things available like Cosmo or Litera or other different boot swatch themes that are available.

For Jupyter, Jupyter lab, again, most of what this will look like is rather than having the auto completion, you have a little bit less kind of interactivity in the YAML because the YAML is not something that Jupyter is normally working with. So it's a literal raw chunk, and we can use that to say, okay, this is what the interface looks like. And you can still type the same figure chunks and the same kind of syntax, but the YAML itself will be essentially ignored by the Jupyter notebook.

If we're using Quarto or Quarto preview or any other commands within Jupyter, from the terminal, we would call something like Quarto preview on our specific notebook. So Quarto preview notebook.ipython notebook, and then we're saying preview it or convert it to HTML. When we do this, it'll pop up a background screen so, again, we can have our side-by-side output. So while you're editing the document, you can save and get the re-rendered output very, very quickly from the terminal, but also having it available as a separate pane.

Again, kind of talked about this a few times, but just want to be very clear that YAML needs to be a raw cell in Jupyter. Jupyter doesn't really care about the YAML, but it's needed and used exclusively by Quarto for these changes. So why did we talk all this time about different editors? Again, I think part of it is that we're talking about Quarto for collaboration and Quarto for more than one community, really like a data science team or across data science teams.

So you might have a website or a data science project or a Quarto project that has something like this. You might have a data link and you're extracting some data with the S3 package and doing dplyr to do some extraction and data cleaning on it with an older R Markdown document you already wrote. And then you're doing some additional data cleaning from one of your Python colleagues who knows Suba and is writing Python code to edit that document. Then it's handed back off and we're working from Python and R and then we're just doing some general exploratory data analysis in it. And then lastly, we have a traditional .qmd and we're using the torch package in R to do some computer vision or classification of the images identifying what they are. So regardless of kind of the different structures you have, you have some R Markdown, you have some Jupyter notebooks, you have some QMDs, across any of these editors and across these different kind of input formats, you can create or aggregate them via Quarto into an overall project or to convert them over to complex outputs regardless of what you need.

Publishing with Quarto

The other part is eventually you're going to want to get whatever you have off of your machine. So you can use the Quarto publish command and that will actually allow you to take a document or a website or a presentation or something else you've created and then publish it somewhere off of your computer. So we have built-in support for Quarto Pub, which is a website that RStudio provides as a free service and you can actually sign up today to get that free service and you can actually sign up today for Quarto.Pub, get your handle and start publishing there for free. Or you can do something like a GitHub Pages branch and publish things to GitHub Pages, kind of like how I'm hosting some of my slides today. You can even use RStudio Connect. So if you have Connect on-premise or in your cloud, you can publish there and have authentication and have it work across your whole enterprise. Or something like Netlify, which again has a pretty generous free tier, allowing you to publish websites and other HTML content to them.

So regardless of where you're publishing it, again, Quarto is extending the idea of R markdown to being a publishing or kind of this bigger project, not just creating things locally, but also baking in the ability to publish all sorts of different things. So lots of different things that you can create and then share out with the world.

As far as for this idea of like data science and work, so for a lot of our customers that are using RStudio Workbench and RStudio Connect, you'll want to use the latest versions. So 2022.07.1 and 2022.07.0. These versions allow for all of the latest and greatest integrations of Quarto. You can use Quarto with older versions, but some of the latest stuff was built in recently. This diagram here, I'm not really going to go into all of the details, but just kind of an overview is that you can use Quarto and R markdown together and publish these complex kind of pipelines as needed on something like RStudio Connect for re-execution or rescheduling of Quarto documents and using them inside an enterprise environment with enterprise-grade authentication and sharing.

Quarto is batteries included

One of the last kind of initial core parts of what Quarto provides is that Quarto is fully batteries included. So if you just install RStudio 2022.07.1, it comes pre-installed and loaded with a version of Quarto. So you don't really need to install anything else. You're ready to go. You can just get started working with Quarto and you don't have to worry about installing a bunch of different R packages to support Quarto. It's just there and always available and will be available moving forward in new versions of the RStudio IDE.

So very exciting moment of having this be available. It coincided with RStudio Conf and having it baked in just allows you to get started faster and collaborate better as you're not having to do additional installs. This batteries included idea goes beyond just having it available rather than requiring a bunch of different installs of different packages. Again, all these different formats are baked into Quarto. So your basic formats like HTML, PDF, DocX, presentations with PowerPoint or the ones I did today with reveal.js or even advanced layout

or websites. You can also do cross-referencing and writing entire books or blogs or interactive and combining shiny things together. You have all these different formats that are just there and already available. You don't have to install something new. The one thing I do want to note though is that there's three things that we're really keen on adding into Quarto. And again, these will be added into this single install in the future. So page down or paged HTML, basically the ability to create PDF without LaTeX and only using CSS. Journal articles and most of that work has already been completed. So you can actually use Quarto to publish to a lot of different journal formats. And then flex dashboard is one that a lot of people are really keen on. And that's also something we plan on having very shortly for allowing me to create entire dashboards through Quarto alone. And again, those dashboards could include shiny, they could include JavaScript or widgets. You can kind of build them as complex or as simple as you'd like.

But core idea here is batteries included. And rather than having to install additional libraries, it's one install with all these things included.

Now, at this point, you might be saying like, oh, this is a lot of exciting things, but I have a lot of R Markdown documents and IPython notebooks and Jupyter notebooks that I wrote before I heard about Quarto. What do I do with those? So for some of you, if you have existing work or you're still working in R Markdown Jupyter, you can just keep working in them. You can still use R Markdown to render them out or to knit them. But if you wanted to, you could still use Quarto to render your documents out. So you could use Quarto render on an existing R Markdown file and render it out to something like HTML, and it'll render it out to HTML. So for the most part, R Markdown documents will convert over as they are. You don't have to change the syntax. Well, you can change the syntax to be more aligned with all the features that Quarto is adding. But again, for older documents where you don't want to edit them, for the most part, you can just render them over.

Why use Quarto?

Quarto is the conversion step of the notebook or the rmarkdown to a final output format like html, pdf, or a website.

To summarize a bit about this, why would you be interested in Quarto? Batteries included with the shared syntax. Batteries included in terms of it's installed with RStudio, so it's always available. If you're in another language or using a different editor, you have this shared syntax across R, Python, Julia, and JavaScript. Based off that, you get to choose your own editor and your preferred data science language. For many of you, and myself included, I'm still using RStudio and I love RStudio, but if you need to collaborate with someone who's using a different tool, you can still do that without having to change into a whole new thing, y'all can collaborate on a shared format.

It also has better accessibility and richer features built in out of the box. There's been a lot of effort for ally work with accessibility, the ability to add things like alternative text and ARIA tags and all sorts of best practices that we're building into Quarto. You can, of course, add on to those, but we've tried to provide best practices for you out of the box.

Ultimately, while our markdown is still being maintained and we have no plans to deprecate it or remove it, we're building most of our new features into Knitter and into Quarto itself. So, over time, Quarto is going to keep expanding. This might sound counterintuitive to you in terms of Knitter is used by both R Markdown and Quarto, so you might have some enhancements going back to the R Markdown world, but in reality, when you think of extending R Markdown, that would be writing a new package. The core R Markdown package itself, it's been very stable for a long time. You have things like Pagedown or Bookdown or Blogdown that are additional packages adding additional functionality. So what Quarto is providing here is, again, that battery's included, and rather than adding on new packages over time, they're added into the core install of Quarto. So lots of exciting things you can do with Quarto out of the box.

So lots of exciting things you can do with Quarto out of the box. And ultimately, this means that when you collaborate or work with others in different languages, again, you have this shared format, ability to choose your own editor, and work in your native language, whatever that is.

And ultimately, this means that when you collaborate or work with others in different languages, again, you have this shared format, ability to choose your own editor, and work in your native language, whatever that is.

Rendering Quarto documents

I've talked a little bit about rendering, but I just want to be very clear in terms of there's different ways to render, and using command line interfaces might be something new for a lot of you. I don't want to ignore that. So inside our studio, you can always use the Render button. The Render button is right in the exact same place where you would have seen the Knit button for R Markdown, but now it's called Render because it's consistently rendering across different documents.

You can also use the terminal or the system shell via Quarto Render. So here, whether it's in just a random terminal on your computer, or the integrated terminal or command line inside RStudio, or another editor, you can call Quarto Render, and then render the document out, and choose a specific format that you want to render it out to. And then lastly, if you really want to use the R package, or if there's some kind of workflow, and we'll talk a little bit about those, where you need to render it out to a different format, you can use the R package to take a document and render it out. So just as you would have used R Markdown colon colon Render, you can use Quarto colon colon Quarto Render to do similar workflows that you'd like to do. And you can choose the output format and provide parameterization and other things that you'd expect via the package or via the command line interface.

Ultimately, what we're trying to talk about here is this change of your mental model. So maybe you're fully bought into R Markdown, maybe you haven't even thought about it. But really, what we're saying is rather than treating your exact source document and your output document as the same thing, like you do with something like Microsoft Office or Microsoft Word, where changes you make are unable to be tracked, we're talking about using code and then a source document and an output document. So with the source document, we have plain text. So we have YAML and we have Markdown and then different code that's at the bottom here. And when we render this out, we get a separate document that actually is generated as the output. So when you're working with something like version control or you're just trying to figure out how did I even create this document, you have the literal source code saying this is how I got there and then this is what I generated.

So you can still have artifacts that you're creating over time, even though the source code of the data might be changing as you move along. You can always try and recreate it or reproduce the work you've done.

Anatomy of a QMD file

When we think about a dot QMD, which is what we're going to focus on for the remainder of today, a QMD file is plain text. So you have metadata with choosing a format or choosing an engine. Obviously, we can choose Knitter and stick with R or we can choose Jupyter and do something in Julia or Python. Then we execute some code. So we've chosen our format. We've got some code in R or Python we want to execute. We go through here and we group by summarize on empty cars. Everyone's favorite data set that's kind of built in or a boring little data set.

But then we can also add text to this. So rather than just executing code, we can add Markdown text and do things like adding alternative text to images or bolding the text or italicizing text or adding headers or subsections. But overall, you can still read this and it's plain text format, but it's indicating this is the Markdown or the markup to generate an output format in bold or italics or other things.

The metadata or that YAML at the top is what's controlling the overall rendering process. So this tells you what is the output format I want to do? What kind of table of contents do I want to do? What are all the different things that I want to do across the entire document as it goes? And again, this can affect things like the code or just the content, the rendering process or how it appears. And it's usually read across by all the different components. So it interacts with Pandoc and interacts with Quarto and interacts with Knitter and affects all the different processes over time.

What the YAML actually looks like is you'd have something like this. It's indicated with three dashes at the top and you do something like, what is the title of my document? And then most importantly, choosing a format. Coming from our markdown, you might have been familiar with the output. Here, we're always going to indicate that as format and then we can do something like HTML, add a table of contents and say that it's true, and then add code folding. So while the code is available, it's hidden behind a little details tag that can be opened or closed. But most importantly, you have three dashes at the top, three dashes at the bottom, and that indicates the opening and closing of your document as you move forward.

The markdown components is based, again, on Pandoc. Pandoc is ultimately the tool that's behind the scenes being converting it out to other formats. And Pandoc markdown is very rich. So you can have, you know, not just the most basic markdown, but really, really kind of expansive markdown that allows you to do layout and kind of structuring of the document overall. So it's based on John Gruber's markdown syntax, and it has the importance of being plain text so that it's easy to read and easy to write. And when you check it into something like version control, your diffs are very easy to also read and write. So rather than a whole document changing if you change one or two lines, the structure is just where you can see the diffs and the different portions that are changed in source control as well.

Markdown might do things like italics or bold or superscript, strikethrough, or even displaying verbatim code. So this allows you to write, again, like lots of different markup about what you're doing. And while you're looking at even just the plain text, you can also kind of imagine what that's going to look like in the output format. And again, if you're using RStudio with the visual editor mode, you can also render, essentially preview what all the different parts are in real time by switching from source mode to visual mode.

Importantly, there's also the idea of headers in Markdown and in Pandoc Markdown. So these allow you to break up a document by adding pound signs in front of text and say, this is a head section, and then you can build up subsections within each of those. So you can write out your headers and do overall complex kind of layouts of your document.

As for code, and there was a good question I saw in the chat. So with Knitter, you can execute R code and Python code together. That would be using reticulate , and that's an important idea. You can merge them both into the same document. So here I have a code chunk. It's just executing R, but via reticulate, I could execute R and Python code together. If I wanted to use Python alone, I can use Jupyter as my engine, and R doesn't have to be involved in that process. So you don't have to go to a Python colleague and tell them, hey, you know, there's this cool tool we could collaborate on, but you have to install R, and you have to use R packages to manage it. They can just use it in their native language without having to install anything else.

We're going to talk a little bit more about what code chunks actually build up with in the second half of today. But you might notice that there's this hash pipe syntax at the top indicating the chunk options as opposed to putting them into the chunk label where they might have been before. But regardless, you have this ability to, in a Quarto document, just like I'm working on today, write code that generates outputs. And it can do more than just R, and you can actually have, you know, insertion of graphics in Matplotlib or using NumPy. So again, we can mix R and Python together in Knitter with Reticulate, or we could have a Python pure document that's using just Jupyter as its engine and doesn't have to have R in the full process. So it's more than just R, and you're able to collaborate with your colleagues.

Using the command line interface

As far as the command line interface, again, you can call Quarto dash dash help inside your terminal, and that will open up a lot of different things for rendering the documents out and display some of the features that are available. Most importantly, you want to make sure we're going to be on, like, 1.0.35 or more recent. That is kind of the 1.0 stable release, and that's what's bundled into RStudio as well as in RStudio Cloud. If you wanted to see the help from the terminal, it would, again, be Quarto space dash dash help, and that will open up the help page that you see here. And the two most common things you're going to use are Quarto render and Quarto preview, which allow you to kind of generate the document or preview the document out to a different format.

For some of you, working the command line may not be something you're used to, but for others it might be like, oh, yeah, that's great. I love using command line tools. If you wanted to go really deep into understanding, like, how to use different command line calls or work through different things, the data Carpentries has a link here on the page that goes out to a great workshop they have. Or there's a tool called TLDR that allows you to kind of ask questions and say, like, what is this tool? Like, how does it work?

I did want to include some really common commands just so you have them available. Things like printing the working directory or changing the directory so you can move between folders, list the directory contents with LS, ask Quarto what are the different things I can do with Quarto dash dash help, make a directory or move a directory, allowing you to kind of work through all these different things you're able to. So while you may not have to work in the command line interface, just wanted to provide these as helpers for if you need to.

If you want to go into kind of the first part, there's this ability to render and it kind of walks you through rendering a document with the render button and ultimately with this 01introhistory.qmd, we're recreating an article about Boston Terriers and recreating it with this single source. So we have that ability to create a specific document, render it out to HTML and to PDF and see the differences and compare them.

So that was the first section. We still have about an hour left that we're going to do in the second section. But because it's a little bit longer today, I do want to take a five-minute break. So we're going to meet back here at 11.55 my time, which might be different for you, but we will prompt you back here in five minutes.

I'll answer some of the questions that are popping up in the chat. I do want to address some of those, but we'll give you a break if you need to use the bathroom or get a drink of water or anything else.

And I just wanted to say, I know for some reason, YouTube was blocking the Slido link when we were trying to share it. So I can share that on the screen as well if you want to be able to ask anonymous questions too. While we may not get to every single question, we are definitely going to take those and answer them in a follow-up blog post and other formats as well.

So part of the reason why I really appreciate Rachel being here is she's helping out a lot. And for some reason, my computer decided it wanted to share things a bit blurrier. So while I'm not going to be driving everything on my screen, if you're looking at it right now, it might look a little bit blurry, which is kind of why Rachel is being kind enough to lead the example.

But I just want to mention that in our studio, if you've never used it before, there's the R console at the very bottom left, typically here, or there's the actual command line terminal. So if we wanted to, we can obviously switch between R and one plus one, and you can execute R code from the terminal is where you'd actually say something like Quarto dash dash help. And then it'll pop up all the different commands that the Quarto can run. So that's where you're going to be looking for it is the terminal inside our studio.

The other main feature is that quarto.org, and I'll drop that link into the chat, is an amazing resource. And it has a really strong search bar here at the top right. You can search for whatever you want to learn about and ask questions there. Ultimately, it has the Get Started tab that allows you to explore different things and get started just out of the gates, or the guide is much more guided in terms of specific topic and the different things that you want to ask.

So there was someone who asked, can I run the Quarto CLI at the terminal inside our studio? Absolutely. That is what we're expecting people who are using our studio to do is use the integrated terminal. But for other editors like VS Code or Jupyter, you might use a separate terminal or spin up a new terminal kind of ad hoc as needed.

There were a couple questions about different formats. So you can change those via the YAML, or you can do it via the command line interface. So again, if I wanted to render a document, and part of the example that we're working on here is in the Quarto workshop under intro, we have this .qmd file. If I want to, I can just say Quarto render 01 intro, actually, let's move into that directory. Another good example of let's list and see where we are, we're in Quarto workshop, let's do quarto-workshop01.intro. So I'm moving or changing the directory into this subfolder. I can Quarto render history.qmd, and it's going to render it out to an HTML format. Or in this case, because I've changed it to a PDF initially. So it'll render it out, I've got a PDF. I can pull that up in my browser, make it a lot bigger. And while it's a little bit blurry on my screen, you can see that we have a pretty nice looking PDF document with some pretty complex type setting and using images around the text as well as in the sidebar.

If I instead wanted to render that to HTML, I could say Quarto render, let's say, history.qmd to HTML. When I render it this way, now rather than rendering it to the default of PDF, I get an HTML file. And I pull that up and we'll get it as self-contained. Apologies, I'm very zoomed in because I want you all to be able to see the content here. So in the YAML, I can render that HTML out, render that, and I have the similar looking complex layout in HTML.

Now while you didn't see any of the real code in that document, and again, I apologize for being a bit blurry. What we're trying to take away here is that I wrote no LaTeX and I wrote no CSS. I only used Quarto to typeset this document. So Quarto has a lot of information that are kind of structuring its building in to build things in different formats. So it's opinionated in a good way to give you nice defaults.

What we're trying to take away here is that I wrote no LaTeX and I wrote no CSS. I only used Quarto to typeset this document.

For some people who are asking, and it's a great question, if I'm in the terminal on Linux or on Mac, let me clear this out, do a new terminal, zoom out just a hair there. So I can call Quarto render on something. On some flavors of Windows, you have to do quarto.command. This is a very specific thing on different flavors of the terminal, and in some cases on Windows especially, you might have to use quarto.command, and then you can do something like help on Linux. It's not going to understand that, but inside the PowerShell or inside Git Bash flavored terminal inside Windows, you might have to namespace that. So great question, Rebecca, thank you for indicating that.

So while I would love to screen share everything, it again is a bit blurry on my side. So I'm going to hand it back over to Rachel, and I'm going to move back into the slides here in about a minute.

So Rachel has opened up the RStudio Cloud link, and we'll drop that into the chat here in a second. You can't actually click on it on the screen, but it should be showing up in YouTube right now. And Rachel also put it into the restream chat, so it should be available. So this, if you go that route, allows you to essentially get started immediately with the workshop materials as we see them. So you don't have to install additional things. For what I was working on, I was going into 01-intro on the file pane, and then clicking on history.qmd.

And you can see inside the file pane that we have a couple images, the files of PDF and .html. You can always use the render button. So at the top left of the QMD or in the middle, there's a render button. You're welcome to use that, and that's where most people are going to be the most familiar with using it. You're absolutely able to click that. If you click on it, it'll render the document out. Great. We have our lovely Boston Terriers. Basically, this is not Howard, but I pretend it's Howard, my dog, and he's up on the screen.

And if we wanted to change it to PDF, we could actually just go back to RStudio Cloud. And inside the YAML, under new format... So on line five, it says HTML. If we delete that and type in PDF and then a colon, yep, awesome. And then save and render it again. Now we'll actually render out a PDF. And again, part of the excitement of Quarto is that I don't know any LaTeX. That's just not a thing I do.

But now we have that same document rendered to PDF. And again, Rachel and I didn't have to write any LaTeX or any PDF-specific things. We just used Quarto syntax. So you can imagine that I'm writing a journal article, and I want to create a website, and I want to create a journal article that I actually submit to the publisher. Both of those could go from essentially the same single source. And you could write it in a way and have it render out without having to write all the manual LaTeX or write all the manual CSS to typeset it and make it look really good.

I also saw someone mentioned about the specifics for the folder structure. Yes, I brought in all of the files from the two-day workshop I gave at RStudioConf. I didn't want to limit y'all just to the things I can cover in the next hour, but rather give you some of the other formats and other approaches that we can do for documents over everything.

So with that, we're at our five-minute mark. Rachel, thanks for walking through RStudio Cloud with me. That's a lot of fun. And we'll go back to the slides, and I'll move us to the bottom right so that we can not overlap too much.

Also, pretty cool that I can just log into RStudio Cloud there without having to install anything and it just worked. Yeah, absolutely. That definitely helps with having to swap who's the presenter for today.

Authoring Quarto documents

So let me also get my slides aligned with you. If you click at the bottom, and again, the link that we're working off of, we'll drop that into the chat. The overall website is available here. I'll keep that up on the screen for a little bit.

So now that Rachel's back on the primary website, we've completed Intro to Quarto, and we're going to talk a bit more about authoring Quarto. So on the top left, we have authoring Quarto, and we're going to go through that together.

So ultimately, again, we covered a little bit of the high details, but went through them pretty quickly. So now we're going to spend a bit more time talking about how to actually do things as opposed to just about what you can do. So we're going to talk about Quarto documents and mainly about this anatomy. We're going to go through YAML, talk about the different ways you can create formats. We're going to talk about markdown and text, and creating that over to the documents that you're rendering out, and then using code. So using things like Knitter or Jupyter to execute R or Python and Julia code. You add all these things together, and you have those beautiful, powerful, useful outputs, and again, you're creating them with a plain text input. So you don't have to write all the different things while you can embed raw CSS and raw LaTeX and all these other different things into it. Quarto provides a lot of power to do all that just through what's built into Quarto.

This is really an extension of the idea of literate programming, basically the idea of writing out program logic in a human language with included code snippets and macros. So if we look at a plain text document like we have here on the page or a QMD, we have the title, which is highlighted here in purple. That's the YAML and all the different metadata about the document. We have yellow or kind of this off pink here that is highlighting the air quality, the relationship between temperature and ozone level, basically the markdown that you're working on. And then the code, which is highlighted here by the R chunk, and it has a label of figure air quality, as well as some code to generate a graphic via ggplot. So this idea of literate programming allows us to build up different components and write out the document as you'd like in real time in a linear way, like top to bottom, but structure it and add up all of the actual literate part in additional to the code that you're writing.

So first we'll kick off with metadata or that YAML that's at the top. Metadata or what's called YAML, you could say it's yet another markup language or YAML and markup language or whatever you want to say. It follows the structure of these key value pairs. So you have a key, something like title, and then you have the value you're inputting, something like this is my first Quarto document, and you're putting that in as text. That's the general structure that all the YAML will follow of just matching some option

with what the option you've chosen. So we think about like output options, going to the next slide, we have format is something. So format is the keyword that's saying this is the format we're choosing to render to, and the value is something we're choosing.

Now we're not going to say something, we're going to choose something like HTML or PDF, or for today's slides, I used reveal.js to create these interactive HTML slides that allow me to step through it. And again, it's available through open source. So it's not something else I have to install or something else I have to buy. It's all built into that as a different format.

You can also add option arguments or kind of sub commands to this. So I'm not limited to just saying HTML, and then I'm done for the day. I could say I have a format, and then I go down to a new line, and I have HTML. And then on the next line, I have table of contents equals true and code folding equals true. So again, I can control the structure, control the options within my format by adding these sub options to it.

Sub options are going to be below. This is slightly cut off in terms of if you click F, Rachel, it'll go full screen for you. So it's going to have the sub options of option one and option two. The options are not limited to just plain text or just, you know, logicals like true and false, but they can be a mixing and matching. So some options might be logicals like true, false, or other. Some might be text where you're having to quote it, and that's okay. It's just depending upon what the options are that you're editing.

Why use YAML for options

Now as far as why you would actually choose YAML is that you might need to avoid mainly typing out all these different options. You know, if I just have a document like we showed in RStudio Cloud, it's pretty easy to say Quarto render document to HTML. Yep. I got that. That's easy enough where I can have fun with it and change it around.

But if I wanted to start adding additional things, I can do those via the command line, but it gets a bit tricky in terms of like Quarto render document to HTML, add some options where code and folding is equal to true. Not too bad. But then I have something really long, and I have this like Quarto render document with code folding parameters, and it's running off the page. It's too long. So while you can absolutely use that, maybe you have it in like continuous integration or something else. It's much easier to write this via YAML, and that's why the YAML is provided is to structure these different options.

It's much easier to write this via YAML, and that's why the YAML is provided is to structure these different options.

Navigating RStudio and the terminal

Now as far as navigating within RStudio, I might walk again, Rachel, through this in RStudio Cloud. If you want to click escape, it'll get you out of full screen, and then you go back to RStudio Cloud. For anyone that missed this before, I just want to point out where the console and where the terminal is.

So at the bottom left, we have the R console where you execute R code or you load packages or whatever else you want to do. And then right next to it on the tab is a word called terminal. And so if you click on terminal next to console on the bottom left, now you're at a command line interface or at the terminal inside RStudio Cloud, although it might be organized a bit differently on your specific computer. That's where you could execute the Quarto command line interface as opposed to the R package that would be executed inside the R console or in a .R or .qmd file. So just wanted to make sure that we have that differentiation between the terminal exists, you can execute code there. If you just installed Quarto, you might need to restart RStudio. For example, like if you install them separately, or if you're making changes, you typically want to refresh to make sure everything's available.

Rendering and background jobs

The other part you might see is that when you click, say, the render button in RStudio, it's actually going to open up what's called a background job. It's going to start this and maintain a background job for you. Part of why it does this is when you click the render button in RStudio, it both renders the document out and then maintains a stateful browser or kind of web server in the background. So as you make changes, you can re-render it and get the full thing built up together. So this is really useful for things like websites or building out complex structures where you're adding a lot of different components and you want to see how they all interact.

If you did something via the R console, it would actually execute just as it was and render out the document without the background job. Or if you executed something via the terminal, it would just execute it via the terminal and not create a background job. But the Quarto render button specifically will start this background job and maintain it in the background. You could always kill it off or stop it if you wanted to stop that from being rendered in the back.

For today, I saw a couple of questions about the recording. So this is on YouTube right now and you can access it in the future via YouTube as well. So it'll be both the live version that you're watching right now and the recorded version will both live on YouTube at the link you're at right now.

Again for rendering, if you click that render button, that's where you get the background job. But you can also call it via the terminal in Quarto render or via the R console via the Quarto R package and call them Quarto underscore render. So all these are valid. There's not really a requirement to do it one way or the other. Just part of it is what are you needing to do? Like are you trying to render a document to different formats? You could do that very easily via the terminal or the R package without having to modify the document.

I have rmarkdown documents and I want to render them as is to Quarto. I was like what all do I have to change? Do I have to change a lot of things?

Rachel, did you have a question? Sorry. I noticed there was a question that's been asked a few times, so I just wanted to ask it. Is there a shortcut for the hash pipe? I don't think there is, but if you type one hash pipe and click enter, it will automatically add those below them. So basically, once you've inserted one hash pipe, as you go to more chunk options, it will automatically insert the starting structure of the pound sign, the vertical line, and a space for you. Thank you for that question, Rachel.

Converting rmarkdown documents to Quarto

So for people that say, I have a bunch of rmarkdown documents, I want to apply it across different things, or I want to convert them over to Quarto, you can generally just render them via the command line. So you can call Quarto render on a document and render it and force it to be used via Quarto. If you wanted to modify your YAML and make it Quarto specific, you could change two primary parts. You change output to format and something like HTML document to HTML.

There are smaller things of things like number underscore sections. Rather than using that syntax, we're using Pandoc style or traditional YAML style with a dash. But overall, you can see that as you're moving between these documents, that the formats actually look very similar. And again, you don't have to convert all of your documents over. It's more of like keep the existing documents you have, use something like the Quarto R package or the Quarto command line tool to render older rmarkdown documents and then write new documents via Quarto. But if you wanted to convert your documents and change all the YAML, you could do it manually as well if you'd like to.

This is partially off the page, I'm sorry about that, but for the YAML for Quarto, the big important part here is again, Quarto is going to have this like word dash word syntax, like we think of number dash sections on line five under Quarto, as opposed to our markdown is using an underscore for a lot of different things. So if you want to be more consistent, that dash syntax is what we're looking for.

A couple of good questions about rendering like a parent QMD that has rmarkdown files as its children. That's a pretty specific thing in terms of you're bringing in code from an rmarkdown file. If you're just reading in the lines of code, that's fine because you're not actually rendering it to rmarkdown, you're rendering it to Quarto. But if you have to say like a Quarto project or Quarto website, anything that's .RMD within that will actually be rendered via Quarto. So you can't like render something to rmarkdown just like out of the box via Quarto. It's going to be a Quarto document at that point. It's just going to try its best to convert it over.

Good question. Within the workshop material, I have what's called like an old rmarkdown. Again, without changing anything, I can render it to Quarto by using the Quarto command line interface or the Quarto R package. Or I can manually go in and change .RMD to .QMD, and that indicates, hey, use Quarto. Or I could change the format from output to format to convert it over via the YAML header itself.

Now, as far as this conversion process, well, again, it's not required, and many times you can kind of render something as is. Option one is I want an rmarkdown, I want to always use Quarto for the rendering, change just .RMD to .QMD. That tells RStudio and that tells Quarto, this is a Quarto document, render it as Quarto. So it'll force it to be executed as a Quarto document, no matter what is in the YAML.

Option two is you can manually change the output, like output equals HTML document to something like format equals HTML. And again, this will force using Quarto, even if the extension is .RMD.

The last option, though, here is, you know, you've got a rendering to Quarto, but maybe your knitter chunks, your code chunks are different. So there is a function in the dev version of Knitter, as of a couple days ago, that allows you to take syntax like fig.width equals one. One more time, there we go. So fig.width equals one, and it'll convert it over to the hashpipe syntax. So that'll allow you to take an entire document and very quickly convert all of the Knitter syntax over to the newer syntax. I wouldn't necessarily use this like all the time. I'd rather just write them as they're supposed to be moving forward. But if you have older documents, this would allow you to convert the chunk header into the hashpipe syntax.

Again, you don't have to convert everything. It's backward compatible with the older chunk options. But if you want to be consistent or you want to kind of move towards a syntax that allows you to be more consistent moving forward.

Layout options for figures

The other part was, you know, we talked quite a bit about this fence div or these Pandoc divs and something like the colon, colon, colon, curly brackets, layout, or layout number of rows or number of columns. Again, we're getting consistency here between something you can do in Markdown, as well as something you can do with code. So if we click through this twice, we're going to have the code and then we're going to highlight line four. Layout number of column equals two is the exact same syntax I use for fence divs to typeset images. But now I'm using it for generated graphics in R. So I can get side by side images, obviously on this presentation, because it's in horizontal landscape mode, they're kind of running off the page. But on a larger document or a more traditional portrait page, I would have two side by side images and the layout structure will look nice there.

I can also use the online seven by click through one more time here. I get layout and I have that again, percentage style. So now I have 40 percent for image one, 40 percent for image two and negative 20 percent of blank space in the middle. And when I do this, it's generating, again, two graphics with blank space in the middle and also applying the figure caption and the labeling of those in my entire document. So a nice ability to, again, have consistent syntax of typesetting and arranging your documents, whether it's bringing in raw graphics off disk or generating graphics on the fly in R or Python or Julia.

Aesthetics and theming

The last part that we're going to be covering today or kind of a last focus is more about aesthetics in terms of you probably have strong opinions about what your things you're creating should look like. I really like the defaults in Quarto. They're really good. They generally follow nice examples of like contrast for accessibility. But perhaps you just have a very strong opinion about what the overall document should look like. So, number one, for things like HTML, Quarto's HTML is styled with Bootstrap 5 and has these opinionated defaults. So Bootstrap is a popular CSS framework, very common for responsive websites. And version five is the latest version of this. Quarto comes pre-installed with 25 themes from Boot Swatch, which is applications of Bootstrap across different themes. And you can go into HTML, call theme and then choose a format like Lettera or something else to change the different format to something else you want to see.

So Lettera is one that I really, really like. That's what I use for my personal blog. It's nice and has a overall good section of like this is what's available. You can also use a specific theme and further customize components with SCSS or SAS. So maybe you really like Lettera, but you want to change a few small components. You can do that with custom .CSS files to modify specific components and use everything else.

As far as the bootstrap themes, those in action would look something like what I'm displaying here on the screen. So if we move through these, we have a basic blog with something like Lettera. It's very minimalistic and very high contrast. You could switch over to something that's like in a dark mode that has primarily like a dark blue background with lighter gray or white text in front or this really nicely themed kind of lavender or light purple. And again, all of the components are changing in unison. So whether you're doing a blog or even just an individual HTML page, all these components will be changed automatically. And you have nice visualizations as well as the nice theming of your blog itself.

I included a section underneath 04 static for boot swatch themes and again link out to a lot of the different available themes. So HTML themes from Quarto.org and all this stuff that's available there.

Reveal.js presentations

For presentations for today, thanks to Rachel's help, we've been working through kind of a unison reveal.js presentation. So Rachel's been driving it and I created it initially. And you're able to create these pretty easily with just a little bit of code. So a very basic reveal.js presentation would look something like this. And I have a title, my first presentation, the format is equal to reveal.js. And then I create new slides by creating level two headers. So like slide one, slide two, slide three here on the page, each of which has two pound signs indicating a level two header. Within those, I have a few different lists. So I have like lists for content and content. I have an image I'm bringing in and I can even display code. So all the presentation you've seen today over the past about two hours has been covering Quarto by creating a Quarto presentation with Quarto.

So all the presentation you've seen today over the past about two hours has been covering Quarto by creating a Quarto presentation with Quarto.

So very, very meta, but a nice way of displaying code and talking about code with graphics as well as programmatically creating presentations. Important parts to note here is that you're going to create new slides with level one or level two headers. So that'd be like pound pound heading. And then you can add content or list or images or codes within each of those pages and just fit them into whatever the overall structure of your page looks like. Again, if we use our fence divs, we can use that to create columns. So I might have some content on the left, more content, an additional list, and a paragraph of text that is important to hold on the left, but it's fun to include below the list. And on the right, I have a nice picture of Howard, who is like he always is, just sleeping with his head smooshed up against the left side of the page. But by using these columns, I can overall structure my document and put them side by side.

That basic syntax, if I'm putting it together and kind of deleting some of the text, I'm again using fenced div syntax. So I have four colons because I'm going to nest two fenced divs within it. So four colons and then a .columns with an S. And then within it, each different column I'm creating, I'm just creating two here, will be its own fenced div with a .column class, and then an additional .fragment so they show up as I move through the presentation. And then I have my image, and again, including some alt text of a picture of my dog Howard sleeping with his head smooshed against the side of the table. But again, you can put it together this and without having to manually align with HTML, you can just use Quarto syntax to create your presentation.

That's all I'm covering on presentations for today, because we are going to have another workshop going over presentations alone later on, because you can do more than just HTML, although I really like Reveal.js presentations.

Quarto projects

The last part we're going to cover for today in total will be Quarto projects. And again, don't forget to come to Isabella Velazquez's presentation. She's going to be coming and talking to us at the end of August, August 30th, to talk about Quarto projects and building your own blog with Quarto. And I can almost guarantee you that you can have some type of working blog created in under an hour.

So Quarto projects, number one, are directories that provide a way to render all or some of the files in a directory with a single command, something like Quarto render my project. Another one might be a way to share YAML configuration across multiple documents in terms of rather than writing a bunch of YAML for individual documents over and over, I can use a Quarto project to apply the same YAML to an entire directory of five or 10 or even dozens or hundreds of documents. It also allows me to control where documents are rendered to. So I can redirect my artifacts out to a separate directory and have a clean directory of experimentation and then the actual final output to a separate directory. And most importantly, I think, for things like blogs or other complex sites is I can freeze rendered output. So you can imagine that I have a blog post from four years ago using some code with a package that may not even exist anymore. Rather than having to re-execute that four-year-old blog post every time I render my blog or my website, it will actually store the computation and freeze that output for me. So when I render everything else, it just renders the new thing or the things I'm telling it to render.

And in addition, projects allow you to create essentially aggregations. So you can imagine a book or a website is really just multiple Quarto documents or HTML pages or PDF pages that are combined into a single output. So just like the website for accessing the content you found today or a book or anything else you're publishing, you can create much more complex things by using Quarto projects.

For what a Quarto project looks like, you might have a minimal one that looks something like this. It's always going to be created with a underscore Quarto.yaml file. That is always what the file is called to create a Quarto project, underscore Quarto.yaml. And that will affect everything in its directory and subdirectories of it. So for number one within the Quarto.yaml, it's a project. And we're not saying it's a website or it's a book. We're just saying this is a Quarto project and I want you to take everything I create and throw them into this underscore output folder. And I can apply some YAML across all of them. I want Table of Contents to always be true on a number of sections. And I have a bibliography that I want to bring in for all of my citations. Then I can also say that I'm creating these in both HTML and PDF at the same time. So for my HTML, I can apply custom styling with CSS and use a specific math method. And then for PDF, I want to create a report and customize the overall layout. So it allows you to kind of structure all these different things, create a new output directory with all the files that you're rendering. And it could, again, be many, many files and control it for different syntaxes in HTML and PDF.

Wrapping up and Q&A

Again, we're about three minutes away from being two hours. I'm going to stick around for quite a while to answer questions. Thank you for all the great questions. But if you want to learn how to build a blog or really create like a complex Quarto project, make sure to come and join us for Isabel Velasquez's presentation, August 30th at 12 p.m. Eastern. You can add that to your calendar as a reminder with rstd.io slash Quarto dash blog. And that will allow you to be reminded a couple of weeks from now that, hey, this presentation is happening. Again, it'll be on YouTube and it'll be recorded and live streamed for your viewing pleasure.

As we kind of wrap up for today on the actual presentation and get more into Q&A and answering a lot of the good questions you'll have, I want to give a huge shout out to the entire Quarto development team. Quarto is really a labor of love and crafted with love and care by the team. So development of Quarto is sponsored by RStudio PBC, soon to be Posit PBC. The same core team works on both Quarto and rmarkdown. So you shouldn't be afraid about some of these changes. You should be excited. Names like Yiwei, JJ Allaire , Christoph, Charles, Carlos, similar people that are working or the same people working on both Quarto and rmarkdown and Knitter. Beyond that, because it's an open source project, there's also a sub link out to all of the contributors and all the people who contributed to it. You can contribute in ways like bug reports or feature requests or feedback in general. And you can get that done at github.com slash Quarto dash dev slash Quarto dash CLI.

To close, in terms of the presentation, don't worry about going away. I'll answer more questions and share some more things. Why you should consider Quarto. Batteries included with the shared syntax across output types in different languages. You have the ability to choose your own editor and your preferred data science language. We will be doing a workshop or kind of a webinar on using Jupyter and VS Code and Python with Quarto. And doing that as a separate webinar so we can dedicate enough time to it. And that rmarkdown is still going to be maintained, but we're building all these new features into Quarto. So rmarkdown has a huge ecosystem that we're still supporting and still maintaining. But we're adding in new features into Quarto so they apply to everyone. As opposed to building out individual rmarkdown extension packages.

If you want to access the materials, I have full workshop materials from two days that we used at RStudioConf. I have the webinar slides that are linked to here, as well as the RStudio Cloud content. All of which is available on the YouTube page as well. If you have follow-up questions, I'm going to do my best to stick around for a while and answer some of those. I know that some of you all, two hours is a big commitment, so maybe we'll see you later. If you have questions, you can ask them on community.rstudio.com underneath the Quarto tag. Or again, I'll stick around for a little bit today or reach out anytime on Twitter.

With that, I'm going to bring Rachel back on screen. We can drop the presentation and we can go back to the talking head format. And the exciting Rachel and Tom show as we talk about the morning and Quarto itself.

Thank you so much, Tom. That was awesome. And so impressed with you just running through with our screen share not working immediately. That went very smoothly after the fact.

Awesome, Rachel. Thank you so much for the quick adaptation and for being a good colleague running through it all.

There are a lot of questions. So many questions. I want to make sure to go over to Slido first to ask some anonymous questions, too. Somebody had asked and it's been upvoted quite a bit. Is it possible to add authentication to a Quarto website? So it's a great question. There's a couple different ways you can think about it. Quarto, if you're generating a website, is just .html or it's just general HTML content. You can publish it wherever you want. Obviously, with things like RStudio Connect, you can publish Quarto to your own server or behind your own firewall and control both the rendering process and the authentication process. For some people, though, they're like, well, I'm an individual. I can't buy and stand up Connect. And that's totally fine. One other option is Netlify has an authenticated level, I think, at like $19 a month.

And you can add authentication to specific pages and host your content on Netlify. Outside of that, again, because Quarto is generating literal HTML, anywhere that you can generally embed HTML and add on authentication could also be done there. So you're not kind of limited. It's just anywhere you can host a website and add authentication, you can also do that via Quarto.

Q&A: Collaborative projects and package versions

So another question that was upvoted was from Kyle. And it was, for collaborative projects with R and Python, is there a recommended method for tracking package versions? Would Rm cover this kind of situation? So if you go to Quarto.org, and I'll grab a link for Rachel to share on the screen here in a second, there's an entire section dedicated to essentially that topic. And that's really what Quarto is trying to provide is a way of allowing colleagues in multiple languages to work together on the same project and not bump up into each other when they're trying to execute their code. So that's part of what projects and managing execution allow you to do.

What this whole section covers is essentially that idea of I want to freeze or control execution. And you can do that with or without virtual environments. So if you scroll down to freeze, you can use freeze to basically say, I want you to freeze the output of code, meaning that even if someone else tries to render it, it's not going to re-execute the code. They don't even have to have Python installed on their machine or are installed on the machine. It's just going to be rendering the HTML or the PDF via Quarto. If you have freeze equals false, then it will always try and re-execute code. But freeze equals true or freeze equals auto allows you to say only re-execute code when I change the source code or just never do it unless I manually force click render on that document.

If you go down one section lower, there's using freeze and then one more subsection, virtual environments. It talks about that you might have a requirements.txt or a virtual environment like a venv in Python or an renv in R. Again, we're not doing a special language. It's whatever you're using in another language is what you use. I most commonly use venv in virtualenv in Python, and I'm using renv in R to control exactly installing specific libraries or a collection of libraries and defining those into a virtual environment.

Q&A: Xaringan themer and reveal.js

I see over on YouTube, Jake, hi, Jake, had just asked, do packages like xaringan themer work with Quarto? So I would generally say, so xaringan is, let's start from the top. Xaringan actually uses a library called remark.js as the way of building slides. Quarto decided to move to reveal.js. The reason why we made that distinction is reveal.js is Pandoc compatible. So you can actually edit presentations in visual mode and get these syntax and, like, the highlighting to work properly.

But I would say so xaringan themer out of the box is not necessarily going to work with Quarto. But the same ideas will. So you can imagine that remark.js, which powers xaringan, there's specific CSS components that affect specific parts. So you can use themes and Quarto bundles a bunch of different themes for reveal.js presentations. I would start there. And then there's a whole subsection on theming or applying HTML formatting to your themes. So if you go to Quarto.org, reveal.js, reveal themes, it will talk about that.

Q&A: Images and layout in presentations

And this was one that was from a bit earlier, but was how does Quarto handle two pictures in the same slide or bullet breakdowns and icons? So if you had a presentation like I had in reveal.js, the images are going to be stacked on top of each other. It's not going to try to align them automatically. It's just going to pull them to the left and inject them one on top of the other. You can use something like the dot columns, fence divs, to put them side by side, almost like Rachel and I are left aligned and right aligned right now in two columns. Or you could use absolute positioning with graphics and you could do a dot absolute class and then say literally from the top or the left or the right or the bottom of the screen, put them 150 pixels to the left and 200 pixels up.

I would probably not put them inside bullets unless you had really small images. You could do icons with like font awesome if they're really small, but generally I would rely on alignment with the more typical fence divs that we showed in today's presentation.

Yeah, as much as possible, using the Quarto fence div syntax means you can use it anywhere. Now there's places where if you try and do five images on one page in a presentation, it might be a bit awkward because you can't scroll vertically. But on an academic article or a website, it makes a lot of sense because you're scrolling up and down and able to move between images.

Is how do R and Python share objects if they're all in one Quarto document? So if you're trying to mix and match R and Python in the same single QMD, then you're using reticulate. You're basically saying I'm okay with using them together. So I have an R installation and I have a Python installation and I'm using reticulate to pass objects back and forth. There's also the idea of like in Python land, there's things I believe like Python 2 R or other kind of libraries like that. I'm not as deeply familiar with them, but I'm very familiar and comfortable with using reticulate inside Quarto.

The alternative is within a Quarto project, you could have a native Python document that someone's editing on a whole different computer, like we were talking about earlier, and an R document that I'm editing on my computer. And we can still collaborate by using freeze equals true. And we're passing just data back and forth like she, Rachel, works on a Python document, writes out a parquet file that I then ingest into R and work on in a separate document. That's totally possible as well, where you don't have to mix and match them in the same document, but in the same project.

Q&A: SQL in Quarto

Can we add SQL script in Quarto? Absolutely. So Knitter actually allows you to execute SQL code in a Knitter code chunk. So rather than using R, when you're doing your brackets, it would be like backtick, backtick, backtick, curly bracket SQL, and you could write raw SQL code. Or you could do something like dbplyr in R to write SQL code via dplyr, and it'll actually do the conversion for you. And I believe in Python, there's a couple libraries like SQLAlchemy that allow you to write Python code that executes actually a SQL as well.

Q&A: Quarto vs Emacs org mode

What are some of the advantages of using Quarto over Emacs org mode? Yeah, so there's a lot of different ways of taking a document with literate programming. Part of that is you have things like Jupyter and nbconvert. You have Jupyter and nbdev. You have Quarto. You have R Markdown. You have raw Pandoc. You have org mode, which is actually an extension to Emacs, where in your terminal inside Emacs rather than an editor, you can write documents with literate programming. Rather than saying what the advantage is, is kind of making it language and location agnostic. Whereas Emacs and org mode kind of says you're basically saying like you're going to work inside that format only. Quarto is really just plain text, so you could use it in any text editor. You could use it without a text editor and just use it inside a terminal if you really wanted to. You can use it like really richly inside RStudio and VS Code and inside Jupyter. And you're meeting people where they are, as opposed to saying like this is the only way to do it. It's like you're allowing different editors and different languages to meet in the middle.

And you're meeting people where they are, as opposed to saying like this is the only way to do it. It's like you're allowing different editors and different languages to meet in the middle.

Q&A: BlogDown and Hugo

Do I love Hugo, or do I not love Hugo? Hugo is the rendering engine that BlogDown uses. So when you're actually using BlogDown, you're writing .rmds or .rmarkdown files that generate .md files. And then you hand over everything to Hugo to render it and create HTML. That is really powerful for creating exceptionally complex and specific websites. I can think of some of the websites I've seen that people like Allison Hill has created that are just beautiful and very functional and amazing.

I am a noted Hugo non-fan. Whatever the opposite of a stan is, I am not a stan of Hugo. It's a separate thing that I have to manage. The BlogDown team has done a lot of work to make it much more user-friendly. But for me, it just was not the right option. It was not something I loved. If you have a very complex workflow and BlogDown's working for you, again, we're going to maintain BlogDown. And you can technically write Hugo-style Markdown documents with Quarto. Some of the things you lose by using Hugo as your rendering engine is things like interactivity, because you're only writing out that md that then gets parsed by Hugo, is you're always going to be limited in the things you can do with HTML widgets or Jupyter widgets or Observable because you're writing plain text.

But BlogDown's very, very efficient at rendering 1,000 blog posts. And I know for some people, like Yiwei, he literally has a blog that's been going for 15 years and has thousands of blog posts. For him, the conversion cost doesn't make any sense. His blog is working great. We're maintaining BlogDown. He's actually the maintainer of BlogDown, so he knows it's not going away. So you don't have to, but I personally switched over to using Quarto blogs from Distill. So if you're coming from the Distill land, I would say there's a much stronger emphasis that Quarto brings a lot to the table that you're familiar with with Distill, but does it better.

Q&A: Mixing text and images, package vignettes

Is it possible to mix text and image content in the layout? So you can. There are certain times when things are a bit more surprising than I'd like in terms of if I'm trying to mix text and images in a table, that's still something that Quarto is working on for making it a really good experience. But with the general block layout syntax, which is very similar to layout number of columns equals two, you can mix and match some text, some paragraph, lists, and graphics together. But still some more work for us to do to make that really, really, really good.

Can we write package vignettes as Quarto? Yeah, so it's kind of a dependency with CRAN. So CRAN is expecting .md and .rmd files. If you were to create a vignette, you'd really be rendering out to a specific flavor of PDF. I don't believe off the top of my head that that's ready to go right now. Edgar Ruiz , part of the team here at our studio, is working on a package called Ecodown, which allows you to write essentially complex websites that encompass multiple packages with Quarto and using that as an extension of more of Packagedown. But again, you're not really getting like the thing you're doing is you're building for CRAN as opposed to building for anyone. And because there's limitations and a focus on what CRAN accepts, all the things you can do in Quarto are not necessarily accepted by what CRAN will accept for you.

Q&A: Getting started with Quarto

What recommendations do you have for people who are just learning about Quarto? How should they start? And what are the best resources? Just do things. I mean, that's a trivial answer in terms of like, that's not fair. But really, it is just do things. If you are creating HTML documents, and if you stick to very simple HTML documents, if you stick to very basic YAML, like literally like format equals HTML, format equals PDF, just start doing some of your daily work there in terms of rather than thinking about, I wrote some .R files. I generated a CSV. I take the CSV and hand it off to a colleague, or I take it into Excel, or I take it into something else. Think about what value does Quarto bring to me?

That ability to mix code that generates graphics and tables and text. Things like lab notebooks or lab reports, or even for like within an organization, like generating presentations with code and graphics and not having to manually rebuild them, or even just normal reports. Like, I got a lot of value out of that during my PhD using things like R Markdown that I may continue to get value out of with Quarto. If you really are thinking like, I just want to learn and like really learn deeply, Quarto.org has the guides. Focus, again, on the subset of topics that you're trying to learn about. Maybe it's presentations and static reports. That's a really great place to start. And there's a lot of powerful things you can do there.

The other part is the authoring section at the very top. That gives you basically what is all the Quarto-specific cool stuff I can do. And again, most of that is format agnostic, as opposed to learning just a specific format. So laying tables or graphics or diagrams or whatever else, you can write out a lot of different things about what's possible in Quarto. The last thing I'll say is come to Isabella Velasquez's presentation. She'll be talking about building a blog. Maintaining a personal blog as basically a portfolio is useful for you to learn things and share that knowledge as well as actually use it in practice. And then if you're looking for your next job or you're just trying to remember what the heck you did six months ago, rather than digging back through notes, you can be like, oh, yeah, I literally have a blog post about that.

So I personally, every time I'm trying to figure out, OK, how do I scrape JSON data from this website and bring it in and plot it? I wrote a blog post a year and a half ago that tells me how to do that. And I don't have to store it all in my head. I can use the reference material I wrote for myself.

So I personally, every time I'm trying to figure out, OK, how do I scrape JSON data from this website and bring it in and plot it? I wrote a blog post a year and a half ago that tells me how to do that. And I don't have to store it all in my head. I can use the reference material I wrote for myself.

And I know somebody put this tip in the Slido link as well, but also recommended to check out Minay's Quarto tip a day. And I'll share this again right in the chat window too.