Beautiful reports and presentations with Quarto | Led by Tom Mock, RStudio

Transcript#

This transcript was generated automatically and may contain errors.

I notice it's a little delayed. Hey, everybody, welcome to today's RStudio Enterprise Community Meetup. I'm joined here by Tom and we're just chatting for a second to see if the LinkedIn stream is working as well. How are you doing today, Tom?

I'm doing great. Happy Tuesday. It's always a good day of the week.

Awesome. Let me go over to LinkedIn and see if we can see ourselves over there.

I'll just mention that for today's slides, the link will be at the bottom of every slide, so you can always copy it from there if you come in later, as well as we're going to be screen sharing and using multiplex for the first time today, which will allow us to actually change the slide on other people's computers, which is kind of neat. So we'll try that out.

Awesome. Well, look at that. It is working on LinkedIn. So hi, friends. Thank you so much for joining today. Welcome to the RStudio Enterprise Community Meetup. I'm Rachel and I've met so many of you already, so thank you for joining back today. I'm calling in from Boston today and we are streaming out to LinkedIn and YouTube right now. So if you've just joined now, feel free to say hi through the chat, maybe where you're calling in from. So excited to have you here for our third Quarto meetup in the past few months. If you missed the past two, welcome to Quarto workshop and building a blog with Quarto. I'll be sure to share those in the chat as well.

But today we are joined by my friend here at RStudio, Tom Mock, who is going to teach us about building beautiful reports and presentations with Quarto. 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 everybody, no matter your experience, industry, or background. So I will also share a link in the chat where you can find out about other upcoming events too, because we have these meetups every Tuesday at 12 Eastern time. We also have a data science hangout every Thursday at 12 Eastern time. We'd love to see you at those too.

I just want to say during the event today, you are able to ask questions on the platform that you're watching from, and it will pull together here for us, or also anonymously through Slido, and we'll share that link in just a second here and pull it up on the screen.

But thank you again so much for joining us here today. I'm so excited to have you with us here too, Tom, and I will turn it over to you. Awesome. Thanks so much for hosting, Rachel, and for all your help in getting this stuff off the ground. We're going to be talking about beautiful reports and presentations with Quarto. It feels a little bit meta in the sense that you're presenting about Quarto, with Quarto, on Quarto, kind of like all the things wrapping up together. And something we're trying out today, and I think one of the benefits of using a format like Quarto or revealjs through Quarto, is that for now, Rachel's actually sharing her screen. So I'm able to actually advance and modify slides on her computer just by changing them on mine. So you can imagine a situation kind of like today, where maybe my computer is acting a little funky, and I'm actually allowing my colleague to screen share or to work, you know, remotely on their own computer, or like for y'all, if you access the slides from the URL at the bottom of the screen, I can actually advance and kind of display the slides as you're progressing through them, whether in a teaching setting or in kind of this webinar style setting. So we're going to get kicked off, and I will run with it.

Visual editor in RStudio

So first off, I just want to mention that, you know, we talk about this pretty frequently, but Quarto and RStudio have very deep integration together. So you have what's called the visual editor. So this is just a screenshot of a few different things from the visual editor mode in RStudio. You can use this to do word processing and kind of modification of Quarto documents, including presentations. And there's lots of helpers there for inserting divs and spans, some things we'll be talking about, as well as things like tables, graphics, links, code chunks, lots of help in terms of making you more productive. One of the benefits that Quarto provides is that the visual editor mode is available for really all the different formats. So again, whether you're writing a presentation or a report or something else, those can all be edited in visual editor mode.

Parameters for parameterized reporting

The first thing we're going to talk about for today, and we've got a lot of kind of content to cover, so I'm trying to provide a lot of overview and kind of exciting broad overview of things that are available in Quarto. So first off, we have static documents or essentially reports that you're writing. I like to think of these as like your daily driver. You know, you can use it for basic kind of exploratory work, but it's powerful enough to also present and kind of display results to your colleagues, even published to a journal or as the final output for your team to share with leadership or other stakeholders. I think Quarto and static documents are most powerful when they're combining this idea of like written thoughts and observations like the human in the loop in terms of I'm adding context and adding prose and text about what I'm working on, but I'm also including the source code there so I can be reproducible in creating my journal article or creating my documentation or creating my report that I'm putting together.

So in that spirit of kind of combining source code with the report they're actually generating, we're going to kick off by talking about parameters and parameterized Quarto reporting.

You may have used these in R markdown, or maybe you never used parameters in R markdown before, but parameters work inside Quarto as a way to create different variations of the same document by changing out small components. Most commonly you see examples of this like I want to create a report for this specific region. So like for today's Tidy Tuesday data, it's you know 50 different states and all the different things that are available within those, and you could imagine I want to generate a report for Texas as well as Massachusetts or New York or California, like all these different states that I want to create separate reports for.

But it could also be covering a specific time period. So if you're doing like a time series analysis, maybe you want to report over the past year, but maybe someone asks you say, okay well I just need the data for the past month. Rather than restarting that report from scratch, you could actually use parameters to regenerate that with just changing out the date.

Or kind of last example, just rerunning a single analysis multiple times and changing components. So maybe you're doing machine learning with Tidy models and you're switching out the different engines that are available for that model. So you can still do like a random forest, but change it out from ranger to the random forest model to a spark model for example. And we'll walk through a few of these different examples.

There's two ways of actually defining parameters. In Python, if you're using that with Quarto, we use what's called paper mill style, which is a way of again providing parameters and generating many reports from one set of source code. In this situation, the tags are actually generated within the code chunk. So you use the hash pipe syntax, then you define tags, and then you have like a vector of parameters that you're creating. So in this case, we have alpha and ratio, they're being defined as both being 0.1. These can be accessed later on in the document by name. So they're not, they're really kind of like first class objects in the situation of like you can't name something else alpha or ratio, those are going to be the actual in kind of memory object that you're using in Python. In R or using the knitter engine, we'll define them in the YAML. So you'll use what are called the params key. And then you can define specific parameters there, again, like alpha and ratio and given specific values, whether the numeric or text or other strings. These are accessed in source code using the params dollar sign syntax. So you actually extract something like alpha from the params environment. In this situation, you could actually have alpha being in the in memory as an object, and then params dollar sign alpha that you can access separately. But generally, you don't really want to name them exactly the same to avoid kind of namespace collisions. The last option here is you can actually define and modify parameters from your command line interface to Quarto or via the terminal. So if you call Quarto render on a specific document, you can modify the parameters with the dash P and then define the new parameter you want to change. So if I wanted to change alpha to 0.2 and ratio to 0.3, I could have multiple calls with dash P and then alpha equals 0.2 and dash P ratio equals 0.3.

And again, so regardless of kind of how you're building out your document, what language you're using, there's there's these ways to approach it and modify the document so that when you're generating it, you can get multiple reports from the same set of source code. Now that we've kind of talked a little bit about what parameters kind of how they're defined, let's actually show a little bit of how those could be used. So I have this example of a pretty simple report. In this case, we're using the Palmer Penguins data set, and we're generating out a report that looks something like this on the right, just as you know, when it was published. And it's got data about this set of penguins and which ones are classified as this specific species.

At the top left this slide on line five of the YAML, it says params equals species equals to Adelaide. So that's the default in terms of if we render this document as is, it's actually going to always generate a report for Adelaide penguins. You know, it's not changing itself unless we say we're going to change it. But we can access that parameter with params$species in a couple different locations. So we can use it in our filter step on line eight of the first code chunk. But we can also use it in inline code with the backtick r params$species. And again, report on it both in inline code as well as in our overall code chunk. But the big takeaway being we could actually change out that parameter to a different species and actually get a whole new report from the same Quarto document. So if we were to do this via the CLI , we might do something like Quarto render that report or Quarto render that report as say like an iPython notebook if we're doing it from Jupyter in that situation. And then we could define specific parameters with the dash p and change species to Gentoo and get this Gentoo report out as opposed to a different name. So we can actually say the output is going to be a new report name because we don't want to overwrite the existing Adelaide report that we've generated. So this is fine in terms of like I can render it with the CLI. I can modify that parameter on the fly. But maybe I don't want to use the command line interface to do this rendering. I could also do it with something like your R code. So I might have a render function I write. In this case, I'm using the R package Quarto and Quarto underscore render. And this allows me to take in an existing report, penguin report.qmd, modify the parameters according to which species we're applying, and then name the report according to again which species we're using. So here we can find all the unique species across this whole data set, walk across them, or regenerate the report with the per R package and render that on each of the three penguin species. This will create something like the Adelaide report, the Chinstrap report, and the Gentoo report, all of which have slightly different parameters that have been modified. And now we have three different versions of the report by species as opposed to having to rewrite the entire report from scratch or copy paste code across. So using parameterized reports like this, even if you're doing it for, you know, really sophisticated, nice looking reports that you're building is one of the powers and kind of superpowers of using code and using things like Quarto to generate out those documents.

So using parameterized reports like this, even if you're doing it for, you know, really sophisticated, nice looking reports that you're building is one of the powers and kind of superpowers of using code and using things like Quarto to generate out those documents.

Another example that might be more applicable to folks coming from like the machine learning aspect is maybe you have a report and, you know, we'll just say that we're adapting it from some tidy models docs. In this case, we're using our parameter of a specific engine. So the default is using the Ranger engine, and we're using that for a random forest model. But we can also change out that engine to any other engines that the tidy models ecosystem can accept. So we can take that same tidy models example report, use the random forest engine, or the Ranger engine, or Spark engine. And again, all, you know, reusing most of the source code, but just changing out that engine and running in a slightly different context. If we do this, we can actually generate out two sets of kind of predictions or two sets of metrics from this report. So, you know, these really don't look any different, but just that we have run the report twice. And if you look at some of the very small value changes, we can actually see that the values did change. So like on line nine, on both sides, we have a prediction of 5.25 versus 5.32. And the accuracy or the RMSE and some other metrics are actually slightly better when we use the Ranger engine for this. So regardless, in terms of like, whether you're trying to regenerate a new report that you're actually using to tell a story, or if you're doing exploratory analysis and doing like different models or different engines that you're trying to run, you can use parameters to modify and decrease the amount of code that you have to write for doing those steps.

Again Quarto wants to support this idea of reproducible science you know whether that's science in an organization and you're creating kind of static PDFs or HTML documents or actually publishing in academia to journals or to specific journals in some cases.

Again Quarto wants to support this idea of reproducible science you know whether that's science in an organization and you're creating kind of static PDFs or HTML documents or actually publishing in academia to journals or to specific journals in some cases. I want to say there's like 10 or 12 journals that are supported as of today but we're also taking kind of feedback from the community as to what other journals are needed and working with specific groups to get those built out.

I also want to call out a nice project from the NFMS open science team so they put together a Quarto extension called Quarto title pages. The tech templates were written by Eli Holmes and the Lua filter that kind of makes it available to Quarto was written by Mikiel and they have reports that look something like this. So yes this is not necessarily like a journal article this is more of like a professional PDF report that you might use in a business setting allowing you to put your company logo and stylize the report in a specific way while also adding subtitles and authors and other things to the document. Something you could deliver in like a consulting setting or in a business setting.

There are additional ones but mostly this is focused on improving the title page which is a big deal in some of the PDFs and making those look really really nice as the default. So I just wanted to call out some great work that they've already done and linking out to their repository that talks more about that.

Presentations with Quarto

So we've talked a lot and kind of gotten through a lot of different things with reports in terms of HTML reports, theming them, including code, PDF reports, and articles and how you can modify those. I want to spend the last kind of section of today talking about presentations. Again I'm using Quarto to write the presentation today about Quarto so I really believe in the tool and its ability to help you tell stories. There's a lot of supported output types and I'll just call out three specific ones. Reveal.js which is an HTML format that's what I'm using today. It has the most power and you can use all of kind of HTML and CSS and even some JavaScript to do a lot with your presentation. But there's also support for things like PowerPoint if you need to work in an office setting or Microsoft Office kind of suite or if you want really prefer working with like LaTeX or PDF you can also use the Beamer format to work with that structure.

So regardless of kind of which format you're going to do I'm going to focus on initially things that are cross-format and then talk about some things that are specific to Reveal.js that are really powerful and exciting in my mind. I also want to call out again two other community resources that I've linked to here on the slides. So Emil wrote this kind of slide craft 101 and we'll talk about that at the end of the presentation about colors and fonts and using them in Quarto. And then Megan put together this nice overview of customizing Quarto slides and adding little section headings that say like you know rather than just being 37 of 58 slides through which section are we on and what's going on in that page.

For the things that are shared across the different formats so again LaTeX or HTML or PowerPoint there's many different things that are shared across that. So you can use what are called incremental reveal or incremental lists that allow you to display specific list elements one by one. You can control the column layout, the title, the subtitle, the author, you know the kind of title page of your document. You can control the headings as well as you're using code so you're able to display that code, hide that code, and actually generate things like tables, graphics, and text as the output of your code that you're generating from your Quarto presentation.

The first thing to remember is you know for creating slides it could be as simple as this. In the YAML header define a specific format so I'm using reveal.js but that could be PowerPoint X or Beamer and then each of your additional slides will be indicated with a level one or a level two header and that's what indicates a new slide. So slide one is a level two header, slide one. Two more pound signs, slide two, and that'll be slide two. And this allows you to structure your document in a way that you can read the source code but the actual Quarto representation knows how to turn it from that source code into the final output that you're creating.

So overall you know very short slide but just one that shows you how quick you can get started with creating slide decks with just a few lines of markdown code.

There's also this idea of incremental lists and an incremental list means that it increments across it. So you might have like three or four bullet points and rather than displaying them all at once you can actually have them be incremental where it'll show bullet point one, then you click an arrow, bullet point two, click the arrow, bullet point three, and so on. So that you can actually walk through your slides like I'm doing today as opposed to them all showing up at one time. So you can do this from the YAML header with incremental equals true or you can turn it on and off via fence divs. So I might have something like this where again I use three colons to start, three colons to end, and then I have an dot incremental class and this will work across any of the presentation formats and it'll say first Howard sleeps and then the next one Howard sprints. He's always sleeping or running around in terms of he's an active dog or he's a very sleepy dog. But you can walk through the different parts of your presentation and control the overall structure in this way.

You can also turn off incremental. So let's say that you had incremental equals true and you want to say that well you know I want to say that Howard eats and then he sleeps. Like that's kind of one thought that I'm putting together even though it's two different bullet points. So if he eats he's immediately going to go take a nap. He's not going to go run around after that. So you can turn on or turn off these incremental lists from the YAML or from Pandoc fence divs with the dot incremental or non-incremental classes.

You can also control the overall structure of your presentation in terms of creating left and right columns or how those appear. This one's a bit more complex in terms you have what's called a dot columns class first and you might notice I have four colons here at the start and four colons at the bottom. This allows me to nest additional fence divs within that kind of parent div. So overall I have a dot columns class and then I'm creating two or more columns that I want to create within it. So within the dot columns class I create another three colons with a dot column and I can control the width so you know make it 50 50 or 40 60 or whatever kind of percentage I want from left and right. And then I'm also using reveal js's dot fragment class that allows me to display the content on the left first and then display the content on the right after that's done. So you can kind of build off of these classes and brackets and fence divs together and overall structure your document across different formats.

Reveal.js specific features

So while those type of things are useful and that gives you a lot of the way in terms of if I stopped right there you could actually get started making presentations like you could actually make a nice presentation from that. I do want to call out some specific reveal js options that are very powerful and allow you to do a lot of different things. So I'm going to have Rachel use one of our secret tips. So on this page we can use alt plus click to zoom into a section and if I pop up this tiny picture of Howard on the screen she can alt click again to back out of that and she can actually zoom in specifically on Howard. So you can imagine that you might have source code or you know something else on the page that looks small but you can zoom in on it to highlight it.

Rachel can also do command plus on her screen that will actually increase the size of things like the url or the logo at the bottom. So she can zoom in a little bit on the page and that will actually make that a bit bigger and zoom out a few times and make the url a bit smaller. Overall just make that part a little bit easier to work with. That's part of the benefit of html is you can modify things temporarily on the fly.

You can also use things called absolute positioning. So like that last image I put it very specifically in the bottom left so that we had to go find it and zoom in on it. I use some code like this another fence div and I use the dot absolute class and then I can say what is the geometry. So from the bottom 25 pixels up and from the left 100 pixels over and then display the image as normally with a fragment class which shows up later. But you can place it anywhere on the screen in that way and really tightly control placement of images or logos or even text that you're putting on the page. It allows you to better tell stories as you're moving through it.

Another one that I really like for reveal.js is using what's called output dash location. This is actually used within code junks so you might have something like this where you're loading the ggplot package doing a quick plot of empty cars and then if I advance the slide it throws that image directly next to it in the second column and it's a fragment so it shows up later. And this again allows you to step through showing the code and showing the output as you're moving through the document. There are many other output dash location classes but just this is the one that I find the most useful in terms of delaying showing it and putting it in the column next to the source code. So I can have long source code and a nice image next to it.

Just like with html or using pdf with different themes or kind of partials you're bringing in, Quarto presentations and specifically reveal.js also come with built-in themes. So there's 10 themes listed here on the page and you can apply those with the theme argument in the yaml header. And again these will change all the different elements of the presentation including kind of the tables, the headers, the background colors, the foreground colors, lots of different elements you can change on the fly very very quickly.

If for some reason you didn't think the theme was good enough or there was something that you didn't agree with you can always customize it further and apply your own custom.scss file to modify specific components of the presentation.

So like for today I wanted to use a very specific font. You know I like the Fira Mono class of fonts for code and at RStudio we use Open Sans as kind of our default font family. So I can import those fonts from the Google Fonts API and then apply some different colors, make the text at the bottom orange, make the level two headers this nice dark blue, kind of this RStudio blue, and also use Open Sans and Fira Mono as my default font and my monospace font. So again I you know not a lot of code but just modifying a little bit to make it look just like I want it to. So using a theme and making it go farther with some of these different customizations.

I can also add a footer or specific logo. So I could use a local image so maybe I have the RStudio logo locally at the bottom right of my slide or I have some footer that says like footer text or a URL or another hyperlink to the source code. For my presentations I like to again use the URL to the hosted RStudio logo so I don't have to keep bringing it around. I can just link out to the URL of that one and then for the footer I can also use the you know a specific hyperlink. So with markdown style code I can say reports and presentations with Quarto and then link out to the slides that are hosted on Quarto Pub. But for this page you might notice the footer is not that in terms of you can actually change the footer as a one-off and if you look at the very bottom it's kind of small but did you see did you notice the footer and using a fenced div you can apply a footer class and modify the footer slide by slide by slide. So for one footer you might link out to this URL and for the next one it could be an entirely different footer. You can override the default that's defined in the YAML. But again that will only apply for that specific slide so if I advance to the next one it'll go back to my overall URL.

At this point you're probably seeing dozens of pictures of Howard in his nice gentleman outfit. I've used what's called a slide background to overlay many different images across that. Not the most effective use of it but just showing you a couple different possibilities of how you can use images or other things as your slide background to tell a story. I did that with you know a level two header slide background and then used these curly brackets to actually define specific things about it. So made the color equals black, the background image was one of Howard's gentlemen, and I made them 100 pixels wide and repeated if they were not big enough to take up the whole screen. Overall there's a lot of different things you can do with this in addition to the background color. You can use a local or a URL to an image, you can make the image cover the background or not cover, make it a specific size, change the opacity or the transparency, you can do a lot of customization to really make it easy to inject background images to your slides. We're not just limited to images, you can also use it with GIFs if you're using those to tell part of your story or tell a joke, and you can even use it to just change the color. So I might do something like slide background background color equals black and this will make the overall body black but make the text white. It will try and always do a high contrast color for changing the font color itself so you don't have to do that manually, you can just change the background color and the foreground color will change along with it.

And just like with images or GIFs, you can also do background videos. These are rather than background image, it would be background dash video and you can control the looping or does it play audio or is it muted, and again things like the size or the opacity. So you could actually embed a full-size video taking up the entire screen if that was what you were trying to do in your slides or in your presentation.

There's some other helpers, so things like R dash stack and combining that with fragments. I can take three images and display them on top of each other very efficiently one by one by one. Again you might have like several different images in unison that you're displaying, so something like here's a Boston Terrier in a field, here's a juvenile Boston Terrier laying down on the ground, and here's an adult Boston Terrier wearing fancy clothing. And you can all kind of stack them on top of each other and apply them one by one by combining the dot R stack and the fragment classes to display them overall.

Custom styling with Emil's approach

As we close out, we've got a couple more slides to go. I just want to again call out Amil's article and kind of how he approached using color and custom styles to apply and change his documents. I hyperlinked out to his article so that orange article will actually take you to his overall blog post, but in his SCSS styles that he added, he included a dot blue and a dot yellow dot blue and a dot yellow class. And these just inject a little bit of color to help tell his story a little bit differently in his presentations. So in action he might write some text that looks like this. He uses bracketed spans to say quarto in blue, enables you to weave together content which will show up in yellow, and executable code in yellow into a finished presentation. To learn more about quarto, makes it blue again, see this specific link. So by doing that, he's using the existing kind of context of bracketed spans but adding in his own custom classes to style the document a little bit differently. And he gets a nice looking page like this where you can really highlight that quarto content, executable code, and finished presentation is the story here.

So while he might read off the slide or I might read off this slide, you can really see that we're focused on quarto content, executable code, and that's a nice summary of what quarto provides. Content, text, and executable code all together. And you can further extend this with what you need to do or what you want to do with writing your own classes. Again he used the bracketed span syntax, so you know square brackets around some text and then applying his specific class to that. But you can also use RStudio's visual editor and he actually talks about this in his article. And you can use, you know, insert a specific span or specific div and then it'll pop up saying what are the type of classes you want to apply to that. So this is really useful for maybe you can't remember all the different syntax, you can actually insert divs and spans with the visual editor inside RStudio.

Wrap-up and resources

That's it for today. We got it all done in an hour somehow. We covered a lot of different things with reports and presentations, theming them including html, pdf, doing reports and presentations together and separately, parameterized our markdown and parameterized quarto and how those are different and the same. And I wanted to give you a few links out to some nice articles and content. So if you just want to read about quarto, you can go to quarto.org slash docs slash guide. That's the overall guide for quarto. But there's also sub links to documents or articles and reports or journal articles if you're trying to publish in an academic setting. I also wanted to call out again a few of the open source efforts by other people outside of kind of the core quarto team. So quarto title pages by the group from NMFS or Emile and Megan's articles on slide craft 101 and quarto slides and what those look like. So a lot of nice content here and you can access my slides at thomasmock.quarto.pub slash reports dash presentations. Or Rachel was kind enough to give me a short link which is much better rstd.io slash quarto dash reports that has all the content for today.

Thank you so much Tom. Really, really appreciate it. This is awesome. I'm just getting started with quarto too and this is really helpful thinking about some of the formatting I was trying to figure out.

There are so many great questions. How long do we have you for? I'm here for the the full journey. So I blocked off the remaining part of this before lunch. So I'm in for the long haul.

Awesome, great. So thank you all for for all the great questions. I did want to remind everybody that you can ask questions in LinkedIn if you're watching there on YouTube live or you can ask anonymously and I will show that Slido here as well. I was also playing around with a few polls as well so just asking if people have used Quarto and what other journals you would like to see. So Tom, if there's other questions you want us to ask everybody else, feel free to put them in the the private chat. We'll go back and forth between YouTube and LinkedIn here.

Q&A: Quarto templates and R Markdown draft

A question from Jimmy was any plans to make Quarto template functionality similar to what R Markdown draft does?

If I'm being honest, I'm not very familiar with R Markdown draft. So give me 10 seconds and I'll look up that function. But just very honestly, I'm not very familiar with the R Markdown draft option.

So kind of like using it as a template is my understanding is R Markdown draft creates and actually edits a draft of an R Markdown based on a template. So there's a couple ways of doing that in terms of the RStudio dev team is working on some more integration of like there are R Markdown templates that exist in RStudio and that's kind of a first class idea of you can like new file, new R Markdown use this specific template. The RStudio dev team is still working on that idea for Quarto. And then for Quarto documents themselves, you can use either the extensions kind of workflow or kind of other ways of bringing in kind of a overall document, importing code or specific chunks and then further modifying it. That's a good option. And I'll go back to the dev team and see if we have some additional thoughts there. But yeah, cool to learn about the draft function and kind of learn something new on these presentations.

Code highlighting across output formats

Thank you. A question from Slido was, can you apply the same code highlighting to different outputs? So for example, HTML or PDF without the call having to be nested under format?

Yeah, so I would say that if you're doing something like styling, you're typically you're taking that step forward saying the defaults aren't good enough. And I have very strong opinions. So I would say the safest option is doing them separately because like PDF has certain things that can do and HTML is certain other things that it can only do. So while there are times where you can reuse the components, like even when I was using the blood theme, which is kind of like a Dracula style theme for presentations, I rendered it to PowerPoint and some of the theming came across basically what changes it could make. But overall, it wasn't one to one per se. So if you really want to go further and customize it, like there's first class ways of doing that in all the different formats. So PowerPoint, you can import a template from PowerPoint. PDF, you can do additional theming or tech partials. And for HTML, you can do CSS or SCSS to customize them. So while yes, you know, for code highlighting alone, there are some options where you can try and reuse it. There might be a time where you get frustrated and it's better to kind of hop out to if you're really trying to do like PDF and make it look a certain way, further customizing it in that way.

Shiny and Quarto dashboard layouts

Daniel asks, any websites that, in your opinion, have the best Shiny Quarto output examples that you could share with others at your company? Yeah, I would say, you know, today, what Quarto provides with integrating with Shiny is traditional websites in terms of there's not a dashboard style Quarto yet. The Quarto team is actively working on dashboard style documents or dashboard layouts with Quarto that will come in the future. But, you know, if you're really trying to invest in like Shiny and trying to make it look really beautiful with Shiny alone, there's things like Shiny Dashboard or Fresh or BS Lib specific to Shiny that allow you to structure and kind of theme those overall documents. In the future, we'll have kind of a better answer for you, which is like, if you're trying to create a dashboard with Shiny and Quarto together, there will be a first class dashboard format. However, if you're creating it today, it's basically going to look like a website that has Shiny code built into it. So I would, you know, go to the Quarto.org. There's a gallery. And that has a lot of the content today and will be updated over time.

Someone else asked, are there built in themes for PowerPoint?

Yeah. So, you know, again, some of the theme components work across formats. So like I was using like the blood theme that's built in for revealjs and some of that came across in the PowerPoint. There is an article on Quarto.org for PowerPoint presentations specifically. And again, once you get into the level of theming, that basically says like, not only do I care about outputting to PowerPoint, but someone has strong opinions about that theme. So if you use what are called PowerPoint templates, that's a first class idea in the PowerPoint world, both in and outside of Quarto. That is how you can use like a company theme that modifies the title page and the layout and the colors and the fonts for PowerPoint specifically. And because that's a proprietary format, there are some limitations around how much we can do that in Quarto, as opposed to how much of that is like the solved answer is use a template that the PowerPoint has.

Organizing long Quarto documents

Another one was, how do you keep long Quarto documents organized for yourself as you're working on a presentation? Yeah, there's a couple ways. If I'm being honest about like writing a presentation, I'm usually have many different things open in terms of like, I have some experimentation files that I'm like testing out specific ideas, and then I'm putting those into the individual slides. But I will say that in terms of like, when I write Quarto documents in RStudio, the level two headers, the code chunks, all those show up in the document outline. So if you use that, you can navigate pretty quickly, even through like an 800 or 900 line presentation. So like today's one, because it's almost 60 slides, I want to say it was around like 700 lines of text overall. And using the outline view in RStudio allows me to kind of move between slides really quickly, especially if I'm like changing something at the title at the very first slide, and then jumping to slide 50. Like using those allows me to navigate the document a bit better.

The other thing I will just mention is that Quarto, regardless of the format, does allow you to use what are called includes. So you can imagine that the final document I'm putting together for leadership might actually be from four or five different people. And they might actually write a specific section, and then you could just import or what is called include them in the parent document. So if you look for includes on Quarto.org, it will actually allow you to access existing content and bring it into the parent document, and actually just inject like all of that QMV or that markdown file in that location. So especially if you have like a bunch of different people working on one thing, yes, you could collaborate across source control, but they could also write their own kind of thing, and you just bring it into the parent.

Converting from R Markdown to Quarto

So essentially, like what are the benefits of converting from R Markdown to Quarto, especially for someone who maybe has hundreds of R Markdown reports? Yeah, I would say overall, the beauty is that we support both in terms of if I say we as in RStudio, like the core team that works on R Markdown is the same team that works on Quarto. So you don't have to change everything, which is a great thing. Like if someone told you tomorrow, hey, stop doing what you're doing and move to this, that would be very disruptive, and that's not the goal of anything with Quarto. There are differences, and there are trade-offs and benefits for using Quarto or using R Markdown for certain situations. But especially if you've got like a thousand line R Markdown report, or you've got a workflow that's working, great, like keep using it. Like we're continuing to support R Markdown. We're not like abandoning it. We are still doing bug fixes and kind of improvements over time.

Just if you think about it with like new features, there were limitations in terms of how we extended R Markdown. The way to extend R Markdown was to write another R package that extended it, and with Quarto, a lot of it is baked into the one install. So rather than having to manage multiple packages or have it be only with R, we're trying to not only improve things for our R users, but also bring essentially like all of R Markdown to the Julia language and to Python and to teams that don't even use code. Like just bring a visual editor and Markdown-style scientific communication without having to manage data science languages. So it's a bit hard of a question to answer in a short format, but I would say just like if you have existing R Markdown, you can keep using them. For basic R Markdown, you can use Quarto to actually render or convert those, but you definitely don't have to convert over.

Like if someone told you tomorrow, hey, stop doing what you're doing and move to this, that would be very disruptive, and that's not the goal of anything with Quarto.

Interactive widgets and checkboxes in Quarto

I see a question from Rob on LinkedIn that was, would things like checkboxes or radio buttons be available or would one need Shiny for that level of complexity?

There's a couple of ways to approach it. So yes, if you want checkboxes and radio buttons that execute R code, then you would need Shiny, right? Because you have to have a server that takes that checkbox you're doing and executes it along with some R code. However, both in R and Python and in JavaScript within Quarto, there are things for checkboxes or cross-language talking. So in R, there's things called HTML widgets and crosstalk that provides basic filters and select with checkboxes and little buttons. In Python, there's something called IPython widgets or IPy widgets that again, give you both a JavaScript kind of framework and then some toggles you can do with it or native to kind of the JavaScript land, but also applies to other languages. Observable.JavaScript is included with Quarto. So you can build out custom kind of interfaces and checkboxes, you know, just through Quarto alone that interact with both R and Python code.

Author arguments and YAML customization

Any plans to add more categories to the author argument in the YAML? Because it's well known you can add authors and affiliations, but it would be cool to also add role.

Yeah, absolutely. So the default things that are available from Quarto are kind of limited to what's available for like the categories in the author. Especially once you get into specific journal formats, the author section and affiliations really expand because certain articles and certain journals want new things added on. Like there are requirements. So yes, some of the journal articles that already exist, those journal article extensions allow for this. And if you're interested, you can also add your own format that adds whatever you want. Like you could add a favorite pet as an author argument to your YAML and just like write an extension that provides that. If you wanted to learn more about that, I would look at the kind of article templates that you can modify on Quarto.org. And those are kind of like .tech formats or CSS that you're bringing in that allow you to further extend what's available in the YAML header. And that's really what those extensions are for, is adding on custom things that you want to see that maybe aren't as generally used.

Including custom HTML, CSS, and JavaScript

Mayank asked, can we include custom HTML, CSS, JavaScript code combination for parts of a Quarto document as we did with our markdown?

Yeah, absolutely. So, there's option, when I talked about includes from before, that include could be used for including child documents or other QMDs. But I also just dropped a link for Rachel called includes, you know, before body, after body, in header, resources, metadata files. Those different options allow you to include, like, literal JavaScript code or CSS or, like, Google analytics.HTML files that are injected into the document. And those are able to be included in a couple of the most common locations. So, before the body, after the body, in the header, like, there's specific locations where HTML needs to inject that type of metadata for it to be used by the website. So, Quarto has the first class support for doing that with the include dash something else options.

Quarto and Xaringan

Arun asked on YouTube, does Quarto work with Xaringan? Yeah. So, there's a long answer and a short answer, and I'll try and do both quickly. So, the long answer is that Xaringan uses a library called remark.js, which is not Pandoc compatible markdown. So, while it was useful with our markdown, it's funny, like, Yiwei was actually talking about it. He never intended for it to be popular. It was for his use. And it required what he called, like, ninja level knowledge to do certain things with it. revealjs is Pandoc compatible markdown. So, that's the one that Quarto settled on as the HTML format is that because you could use it with the visual editor and it was compatible with all the rest of Pandoc, that was the one that they settled on. If you take an existing Xaringan presentation and try and render with Quarto, it will work in terms of I'm putting that in scare quotes. It will render it into some type of presentation, but Xaringan used a lot of custom themes, a lot of custom CSS, custom classes, and different ways of writing that is just not fully compatible with Quarto. That all being said, and continuing the long answer, I was a Xaringan absolute power user, loved using it, and I've fully converted over to doing revealjs. I really, really enjoy it. If I wanted to, I could still write Xaringan, but revealjs adds in a lot of things that clicked with me, and again, the unified syntax across all of HTML is nice, where I don't have to remember how do I do it in this one specific package, but this is the way to do it across all HTML style outputs, and Quarto was a nice option.

PDF templates and LaTeX customization

Any plans of creating tutorials for .txt templates for PDF output for Quarto would be amazing. Yeah, so there's some ongoing work for writing things like Lua filters and other things like that. So, this article I'm sharing with Rachel has some of the information about when you're writing a custom format, what all do you need to include? Ultimately, in terms of while we might end up writing .tech template examples or theming components, tech is its own massive ecosystem, and while you might be able to get introduced to it from Quarto.org, for example, it's such a broad topic that I'd be afraid that lots of things would get left out. So, ultimately, it's like, if your team, you know, what Quarto's trying to provide is a lot of very common and powerful templates, so things like journal articles where I could publish to this journal without knowing any tech, right? Like, that is my mindset. I don't know any LaTeX, and I can still publish in the format that this journal wants. So, JSS wants this, you know, LaTeX file that they're getting. I can do that with Quarto. If I want to customize PDF to go a certain way, I really need to learn a little bit of tech or tech partials to further customize that, and that's a skill that I would need to develop to be successful in that role. So, yes and no in terms of there's some documentation around creating formats and how that can be used for specific things and distributing them, developing filters and things with Lua, but there aren't major plans for tech templates today.

Again, I do want to call out that, like, the open source community has already started building out some of these. So, I'll call it again the S group, and they're in the gallery on Quarto.org. They actually put together source code for, kind of, how they've approached building out those. So, grabbing that content, and if I miss Quarto, Pandoc. I'm going to drop this into the chat for Rachel. So, that one actually talks about how to modify their templates and how to modify and use and DIY some of it. That resource is amazing. Like, it's a great amount of work they did to both do it, but then also write about how they did it. So, while that won't teach you everything about .tech and partials and everything else, it at least gives you, like, a nice structured way of learning. And again, because it's an open source project, over time, additional people, including us and others, will build out educational content or, kind of, extension content around that.

Parameters, dates, and favorite Quarto features

If we know we want to use a number of parameters, do we have to give one of those parameters as a default in the YAML?

Yeah. So, you'll want to define them at least because you could imagine that when you're trying to render it, if you have a – if you indicate it in the body of the document, it has to have a default value. So, if you don't define it in the YAML, then when the document is just rendered with, like, the render button or Quarto render, it's going to fail because that object doesn't exist. And it's like, I don't know where to find this. It doesn't exist. So, you will need to define at least some default in the YAML that's used for the first rendering, and then you can modify it further. That really applies to both, like, the body of the document because you have to write, you know, params, dollar sign syntax, or use in Python, you have to at least, like, use that object. And again, if it's not defined, then Python or R are just not going to know what to do with an object that's not defined.

One of those I thought might be helpful to just cover here, too, is how can we include the current date in the YAML file?

You don't even have to use sys.date. You can do date equals today. Date colon today. One of my favorite someone actually asked me about that this morning just before coming on to the presentation, and it's one of my favorite tricks because it's language agnostic. So, again, you don't have to do it, you know, only within using sys.date, but on Quarto dates and formatting, there's a built-in default for using date equals today, or date equals now, or date equals last.modified. So, there's multiple things you can do with it in terms of, like, did you modify today? Did you modify with a specific time as well as the date? Or when was the last time the document was modified, not rendered, right? Like, those are all separate things, and if you just did sys.date, it's not as flexible as some of those things that are just built-in free options that are awesome now, and I love those things.

Okay. So, Tom, you just got really excited about that one. So, I'm curious. Dates and tables are apparently my thing. What is your favorite thing that you've learned in switching over to Quarto where you're like, wow, that was amazing?

I think the biggest just, like, kind of, like, mind-blown, like, absolute new feature for me was freeze with projects. There's so many little bitty things that are cool, like, date equals today and unified syntax and listings, but if I were to identify one or two, and I just thought of two, we'll stick with those. One is for projects, freeze equals true, which allows me to store the computation for an entire project, like, for my personal blog that's five years old, I can store the computation from the first article I wrote five years ago, and I don't have to re-render that one every time. So, that's super powerful for collaboration or for just, like, managing documents over time.

The other one that's kind of just, like, mind-blowing is website listings, because you can basically create custom listings and build out, like, summaries and cards and little grid layouts of all this different type of content manually or from source files, and just built very nice-looking pages, like, just remarkably complex and in a good way.

One is for projects, freeze equals true, which allows me to store the computation for an entire project, like, for my personal blog that's five years old, I can store the computation from the first article I wrote five years ago, and I don't have to re-render that one every time.

I have to link out to this, and we're going to screen share it, so, sorry, one more, but this is the page that gets me excited about custom listings, and I just dropped that in the chat if you want to screen share that Connect Widgets fake one about listings specifically.

So, the reason why I find this so cool is, like, if you look at this page, it's a summary of a large end-to-end data science task, and we're hosting it on, like, RStudio Connect, but in terms of, like, there's all these different things it's doing. So, it provides this kind of background of where you can say, like, here's the diagram of all the things that are occurring. There's a Quarto document, there's Vetiver, there's APIs, they're all communicating together, and as you navigate down the page, if you go further to, like, schedule jobs and things like that, keep going, there's tabs and cards and other different things that allow you to just, like, move through all these assets you've created. Like, this data science team put together 15 different things that make up this complex, robust data science project, and with listing pages, you're actually able to aggregate these into tables with filters and sorting and cards and all that's natively built into Quarto as, like, a first-class thing. So, you don't have to escape out to...

Okay, how do you do this one? I've been trying to figure out this one. How do you do this?

I got source code for that one. The answer is lots of YAML, but let me grab... I'll share you the GitHub repo so we can share that out as well, because this is, like, the mind-blowing one to me. It's just, like, all of that. I'll drop one more link to you, Rachel, here in the chat.

So, that is a public repository called test-listing, and it goes through, basically, the idea of building the Connect Widgets R package only with Quarto. So, you don't have to use, kind of, the structure of Connect Widgets, but you can rebuild all that formatting with cards and grid and tables. So, I really like this. That was, like, a motivating... Listings are really cool. You should try them out.

That's amazing. Thank you. Okay.

Q&A: Theming and styling

I'll try to go through just a few more questions. I know we could stay on here all day, but we can't, really. So, okay. So, going over to John's question on YouTube.

Is there a styler for Quarto, like an RStudio add-in?

So, there's a package called bslib that has a first-class plug-in for exploring themes for our markdown. I do imagine, at some point, bslib theming will probably be available in Quarto, but it's not today. So, my answer is there is not a RStudio add-in as of this moment in time that might change over time. Boot swatch theme picker. I'm just looking. I believe...

Okay. There might be an option for just, like, modifying boot swatch in terms of, like, those are the 25 themes that are built into Quarto. There's probably an application that hosts a boot swatch theme modifier, because that's really what's happening, is bootstrap CSS boot swatches the opinionated themes, and you can modify them.

So, no, there's not, but that's a good idea, and we're probably already working on it.

Audience poll and publishing to Quarto Pub

Great. Thank you. Okay. Maybe we're having too much fun with the polls over here, but I just wanted to ask one more over there. And it doesn't have to be related to Quarto, but I was just wondering for people listening in, what is a challenge that you've faced in the past few weeks that we could explore creating content for? And it doesn't have to be, like, code specific or Quarto. It could even be about, like, people focus or organization. But just wanted to ask that to everybody as we think about what would be most helpful for you all.

And that's just on the Slido. You can access the poll there. Okay.

One other question from Slido.

Can you please quickly throw light on how to publish a Quarto document to Quarto Pub with the YAML attributes setting file?

YAML attributes. I'm assuming – I don't want to assume too much. Let me make sure.

YAML attributes is kind of a loaded term in terms of –

We could ask for clarification.

Yeah. If you want to clarify on that one. So, Quarto Pub, I would say the best resource is that, like, Quarto Pub is a first-class kind of description with the documentation on Quarto.org.

And it has a publish.yaml example. I think that's probably what you're talking about in terms of that's a YAML file that allows you to modify settings for a specific Quarto Pub. You could include that around the context of, like, your existing project. For most people, the way that you would use Quarto Publish or Quarto Pubs is you would, from the terminal, you would do Quarto Publish, Quarto-Pub, and then the file you want to publish. And it will then walk you through interactively the process of, like, selecting your credentials and, yes, you want to name it this and publishing that. With Quarto Pub and the underscore publish.yaml, or if you're doing that non-interactively with something like continuous integration or GitHub Actions or Azure DevOps or RStudio Connect,

you can go further and basically, like, write some of those ahead of time because you aren't going to be there to do those steps. That's, again, a pretty big thing to think about. So, there's a lot. There's, like, a whole section on publishing on Quarto.org that's fairly new. So, maybe last time you were looking, it wasn't there, but it has, like, description of the underscore publish.yaml, the publish command, as well as the non-interactive publishing with continuous integration. And I think, yeah, I shared that with Rachel, and she'll share that in the chat.

Quarto cheat sheet and reference

Perfect. Okay. A few other questions. One from Slido. Is there a comprehensive Quarto cheat sheet or web page? They clarified and said, I'm finding bits and pieces of code for the YAML header and code chunks, but nothing comprehensive. So, the best option, if you – it's not a cheat sheet at all, but I would consider it more of, like, a reference or an appendix. So, if you go to the Quarto.org slash docs slash reference, or at the top of Quarto.org, there's a reference header.

Yeah. Okay. Perfect. Quarto.org. And then at the top, it says reference, that fourth item. Okay. This provides for all of the formats and different things you can do what is possible. So, these are – this is not expanding on it in great detail. It's just describing it. But let's say for a YAML header, if you click on documents, the HTML, the first one there, these are all the YAML options you can provide. And then they're structured by what is, like, the grouping.

So, this is pretty bare bones, but it, like, tells you what's possible and what does it actually mean. This is also duplicated, so when you're writing Quarto documents in RStudio or in VS Code with the Quarto extension, if you do control plus space inside the YAML header, it will basically pull up this list, and you can start filtering it. So, you can say, like, you know, start typing title, and it will say, like, title is something you can autocomplete and describing it as the document title. But this reference section gives you a massive amount of just I want the highlights or the cheat sheet of, like, all the different things that are possible. And then if you want to go into, like, how would I actually use them, that's where the guide section would be more useful. Okay. And that was control plus space? Yep. Control plus space inside the YAML header or inside a hash pipe in the code chunk will basically, like, pull up a search bar, essentially, of, like, what is possible that you can do inside RStudio.

This is also duplicated, so when you're writing Quarto documents in RStudio or in VS Code with the Quarto extension, if you do control plus space inside the YAML header, it will basically pull up this list, and you can start filtering it.