Creating Polished, Branded Documents with Quarto

Transcript#

This transcript was generated automatically and may contain errors.

Welcome everyone. Again, thank you so much for joining. My name is Isabella Velazquez. I work on the developer relations team at Posit, been there for almost four years. I have been very fortunate to work with Quarto for a long time before it was released generally, and I'm really excited to get to share what I have learned with Quarto with you.

And so if you don't mind, I would love to learn more about you as well. If you would like to share in the chat anything like your name, your professional affiliation, I'd love to hear what kind of things you produce in terms of data products, do you create dashboards, do you create reports, and your preferred programming language. I will say this being R Informa, the exercises that we'll show today are going to be in R, but everything is also doable in Python as well, and I'm also happy to chat more about that if anybody is interested.

In terms of this workshop, it's going to be, like I just mentioned, mainly focused on R, and so if you are somebody who works frequently with code with R, creating things like graphs and tables, and you want to learn about a tool that lets you do that very seamlessly and create really beautiful outputs, that's what we'll be talking about today.

The beginning part especially is definitely geared towards folks who may be new to Markdown and Quarto, so if you have some extensive Quarto experience, this might be a bit of review for you, but I hope to kind of start off everybody in a kind of foundational understanding of what Quarto is and how to use it. And in terms of what I hope you walk away today with is this knowledge of Quarto and hopefully an understanding of how you can apply it to your own work. We'll also be talking a lot about theming documents, so creating styles and themes that you can apply to your documents so that they match your organizational brand or things like that, and then, as mentioned, some examples that you could take with you if you want to go and workshop them further.

An extension system, so both by Posit and by the community, there are a ton of tools that exist out there to extend Quarto, to add new features, to add different kinds of styling and templates and things like that, and it's very incredible the things that people have come up with in order to make Quarto even better.

What you can create with Quarto

And in terms of what you can create with Quarto, you know, I was looking through the Rforma archives, and I was really impressed. There were already so many really great presentations about things that folks have done with Quarto. And so, just to pull out a few, there was an Rforma talk on this, but I also found on the FUSE U.S. CONNECT 2025 archives is this clinical study report document created using Quarto and Shiny . You can also create websites. So, for example, this is a tables listing and graphs catalog by the NEST team.

And in addition to their documentation being created with Quarto, I mentioned earlier the extension system, there is an extension called WebR, which lets you embed executable code within your documents. So, that means there is a code chunk that anybody can run as long as they have a browser and an internet connection without needing to have R installed. They just click run code, and they get the output, which I think is pretty incredible and a great way of adding to documentation as well.

You could create books with Quarto, blogs with Quarto as well. So, this is a special kind of website that has a listing. You could create presentations like the one that you see right now, or here's another example, which, again, is really great in terms of adding that dynamic ability to create different kinds of outputs. Journals. So, if there is a specific journal that you want to apply to, you could create a Quarto template so that you can write it in a QMD file with your code and your markdown. When you render it, it gets to the right style for you. And then a dashboard. This one was presented at PharmaSeg 2024, kind of showing off the different capabilities that we have to embed data output in a really visually striking format.

So, we'll be talking about quite a few of these outputs in a little bit, but I just wanted to give you a brief rundown of what's possible. And, as mentioned, there are specific things that are built for technical documents that Quarto provides. And, in conclusion, it is a great tool for folks who work with code who need to create output and want to do that in a very seamless and effective way. So, that is my brief introduction to Quarto.

Installing and setting up Quarto

So, now we can get started. If you want to use Quarto, the first thing that you need to do is install Quarto. If you have not done this already, there is extensive instructions on the quarto.org website, which is the documentation website. You can see here, step one, you download the CLI . So, CLI stands for Command Line Interface. As I mentioned, Quarto is inherently free of computational systems, so you can run everything in the terminal in the command line without having to install R or Python. The examples we do have today do have R, and so that will be required because of the specific examples that we have.

If you use RStudio or Positron, those are actually – they come bundled with Quarto, and so you do not have to install it separately through that command line interface tool that I just mentioned. But if you use another editor, like VS Code or Jupyter, then you would need to go ahead and install it yourself.

And so, in terms of your options for today, we have PositCloud, which is – if you have not worked with it before, it's a cloud version of RStudio. So, that means that you can use the RStudio IDE in your browser, on the internet, without having to install it yourself. And one of the benefits of PositCloud is that it comes – I have pre-installed all the packages that you will need, so hopefully, you know, you won't have to install anything or run into any, like, missing packages, errors, or anything like that. So, that is my recommendation if you're able to do that.

But you are also more than free to install locally if you have your own RStudio or IDE that you want to use, and the instructions will be on the website for the GitHub page – or, sorry, the GitHub repository to clone. So, now I'm going to hand it to you. So, first things first is to go to this website, which provides everything for today's workshop. Click on the introduction in the sidebar, scroll down, and there will be setup instructions.

Anatomy of a Quarto document

And so, now we're going to be talking about our documents, where we just first opened up the first QMD file. We rendered it. We saw what that looked like. So, that is our first QMD file. And so, we will now talk about, more specifically, what exactly makes up a Quarto document.

The anatomy of a Quarto document. So, a QMD file generally has three different components. The first one is the YAML, as mentioned in the chat. So, this provides the metadata of your document. So, things like title and author, text, which is the narrative, the things that you write to explain what to report to your stakeholders. And the third is code, which could be R, Python, Observable, and Julia. Put them all together, render it, and then you get your beautiful output.

So, the YAML header – YAML stands for Yet Another Markup Language, or YAML into markup language, depending on who you ask. Again, it's the metadata, things about your document that aren't necessarily in your document, but help you in terms of how to render it and what you want it to look like. In terms of the syntax, the YAML header is demarcated by three dashes at the top and the bottom. And then within there are a set of key value pairs in the form key colon value. So, format would be the key, HTML would be the value. And so, these are common things like author, subtitle, date, as well as customization and options like the theme.

The next part is going to be your markdown text. So, underneath your YAML header, the YAML heading is always at the top of your document, is your markdown text. And so, markdown, if you have not heard of it before, is a lightweight language for formatting text. And so, very readable, very easy to construct. And Quarto is based on Pandoc and uses a variation of markdown underneath in that diagram that I showed earlier on. So, an example of how to style with markdown, if you want italics, you can put asterisks. If you want bold, you can do two asterisks. And so, within the text in your Quarto document, you would use this kind of syntax. And when you render it, you get the result where it looks different, right? Like you would if you were to bold something in Microsoft Word or something like that.

And then, the third part of a Quarto document is the code. And in terms of actually creating your code chunk, they begin and end with three backticks. Usually, we'll talk about the usually in a bit. And the code chunks are identified with a programming language in between those curly braces. And another important thing to note is you can include what are called optional code chunks inside of your code. I'm sorry, your chunk options in your code chunk that kind of change how things are rendered when you create your output. So, for example, here on line 11, you can add a code chunk option with the hash, sorry, the pound sign and then that long dash, or I'm sorry, line. And here, it says echo is false. So, echo is false means please render this, but don't show me the code, which is very helpful if you are, for example, presenting your report to somebody who is not interested in the code and just wants to see the output.

There are a variety of different code chunk options. And so, linked here are the other execution options if you want to include them in your document or in individual code chunks.

And I mentioned earlier code executable code is usually in code chunks, but you also have another option of doing inline code, which executes code within Markdown. So, in your Markdown text, if you do the backtick R and then a value that has been defined earlier, in this case, P value has been defined as 0.003, and then you can refer to it within your text using that syntax. And when you render it, what it will output is whatever the value of that object is. So, in this case, instead of saying P value, it's going to say 0.003. And so, this is very, very powerful if you are referring to things within your code or within your data in your narrative so that you don't have to hard code values and update them if your code changes or if your filters change or your data changes or anything like that.

And so, this is very, very powerful if you are referring to things within your code or within your data in your narrative so that you don't have to hard code values and update them if your code changes or if your filters change or your data changes or anything like that.

First exercise

So, let's give this a try. So, for the first exercise, I would like you to please open 01-exercise.qmd, the same file that you rendered before. Add and include false chunk option in the first cell. In the YAML, add an author key value pair with author as the key and your name as the value. Change the code fold to be true. And so, somebody asked earlier, what is the option for collapsing the code in your rendered document? So, it is called code fold at the top of your document. And then I would also like you to edit the first paragraph to make something bold by surrounding a word or a phrase with two asterisks and then use inline code instead of hard-coded values for the p-value.

I mentioned there are code chunk options, which you can do within a code chunk itself, like that echo false option. But you can also set it so that it is the case for your entire document. So, in this case, I put execute warning false messages false. So, what that means is for every code chunk, don't show me any messages, don't show me any warnings, which, you know, if you load the tidyverse , for example, there are a lot of messages that come up.

In addition, you can put different kind of settings for your document, whatever output that you want. So, here I'm saying give me an HTML document and here code fold is false. So, that means do not fold the code. But as shown in the exercise, if you set that to true, now it will collapse the code when you render it. So, give it a shot, you know, preview one and then change it and then preview it again so that you can see what it looks like.

Can we include a logo in the YAML file? So, we will be talking about logos in a little bit, but there is a way to include logos in YAML file. Depending on your output, it will show up differently.

So, if you remember in R Markdown, if you want to create a blog, you have to download blogdown . If you want to create a book, you have to download bookdown . And then also within blogdown and bookdown and shuriken and so on,

there is slightly different syntax to do the same thing. Like, for example, create a tab set. I remember in shuriken, it was slightly different. And whereas in Quarto, you can do all of that in a really, like, using the same syntax. You don't have to change it up or anything like that.

Personally, I really like how Quarto looks out of the box, both, you know, HTML files and presentations and things like that. We will talk about dashboards and websites a little bit later as well. And in terms of the different extensions that exist, I think that there is just a lot of functionality that the community has added to Quarto as well. I don't know. I would love to hear from the folks, if you have used Quarto before, if you made the switch from R Markdown, what kind of compelled you to try Quarto and stick with Quarto as well.

One powerful extension that I wanted to add, but I think we would run out of time, is one called Web R, which, again, lets you create code chunks within your Quarto documents that people can run without having to download R or open up an ID or anything like that. So, it's very powerful for teaching and things like that. But I'll think about it a bit more, because it's a great question. Oh, yes. Olivia has a great point, too. If you do have to use Python at any point, it is natively working with Python. And so, you don't have to download, say, Reticulate and work with that. Everything that you see here, if you switch out R with Python and switch out to R code, Python code, everything would run just as seamlessly. Yeah. Okay. that was the exercise. Thank you all for the great questions.

Authoring Quarto documents

Let me see if this goes. Okay. So, now let's talk about offering Quarto. And as I mentioned before, there's specific syntax from Markdown that we can use to do things like create a link, add images and things like that. You could do things like add tables, and you can also customize the table widths if you so choose. Quarto has native support for diagrams. This one is made with something called Mermaid. And so, it is using the syntax, render it, and you get this diagram.

You could do math mode and the tech within Quarto documents as well, speaking to that scientific and technical publishing system part that we mentioned earlier. You can also further customize your documentations using things called div and spans, which add classes and attributes and other identifiers to customize what your document looks like. So, for example, this one, if you were to define it, it would add a border for the div. The second part, whatever class I gave it to the span, when I render it, it will end up looking like that. So, things like changing the color, things like that.

There are several divs that are built into Quarto. So, for example, a callout box surrounding some text with these three colons and then callout tip and then curly braces will result in something that looks like that. So, a really nice and simple way of creating these kind of looks. You can do things like add multiple columns. In this case, we're saying, please put an image and some text in two different columns. Rendering it will result in this.

Tab sets, as I mentioned earlier, these are built into Quarto as divs that allow you to create tab sets. So, here is say your documentation is both in R and Python. You can have a tab for R and then a tab for Python.

As mentioned, spans allow you to customize small parts of your text. Here, I'm making the text red. And then also, there is other kinds of spans that allow you to do things like add alternative text to your images directly within our markdown syntax. So, in this case, this image now has alternative text. So, that's just like a brief rundown of like if you want to start working with your document and customizing it, what you can do.

Output formats

Another big benefit of Quarto is the very variety of the formats that you can do. So, we've been working primarily with HTML, which are like webpages. Changing that T value pair in the YAML heading from format HTML to format reveal.js will transform your document into a reveal.js presentation, which we'll talk about in a little bit. But essentially, like the slide deck that you're seeing right now is made with format reveal.js. And again, all I had to do is change the YAML heading to create a presentation.

We'll also be talking about Typed, which is a relatively new tool for creating PDF in a way that's very, you know, intuitive and follows kind of like the same sort of idea as Quarto, like a little bit more human readable and things like that compared to some alternatives. And again, with all of these formats, all you have to do is have Quarto installed. You don't have to install something for reveal.js or install something for Typed. All you have to do is change your QMD file.

So, to talk very briefly about reveal.js, I just want to kind of introduce like the idea behind it and the structure so that if you want to go and create your own documents, you can go do so. But I think reveal.js is super cool. I think it looks really great. It looks very modern. It's for these presentations that live on the web. It handles code and LaTeX equations really beautifully. And as I mentioned earlier, you can also include live computations and interactive content directly in your slides. And then also it has very cool fancy transitions as well.

So, on the left, here we have a basic Quarto document that if you notice in the YAML heading, renders to HTML. And you can see what it looks like on the right. Changing HTML to reveal.js, now we get a presentation without having to change anything within the document itself. And it looks like this. And you may notice the same content is formatted, but now each level two heading with the two pound signs is its own page now.

Okay. You can continue adding multi-level slide structures with single level headings with just the single pound signs now in the morning. Makes up its own deck. Sorry, its own slide. And then getting up is its own slide with information underneath. And you can also use horizontal lines to act as a slide deck.

There is this very cool extension created by one of my colleagues, which allows you to edit slides in reveal.js like you do in PowerPoint or anything like that. So you can drag and drop text and images right on the slide preview so that you can reposition and resize them. So it saves a lot of time from having to manually figure that out yourself. And then it being code first, it also writes back to your presentation so you can recreate it at a further date.

And another important thing to know is you can really customize your reveal.js presentations. And so you can do that manually, like on a presentation by presentation basis, kind of like this slide deck that you're seeing here. But if you ever find yourself repeatedly using the same template across multiple presentations, you could create what are called templates. And we'll talk about templates a little bit later in terms of sharing our branding and things like that so that other people can or your colleagues or yourself can use that same formatting without having to recreate everything all over again.

Typst for PDFs

And then the next thing I want to talk about is types. And so as I mentioned, it's this new open source markup-based typesetting system that is meant to be as powerful as LaTeX if you ever use LaTeX for building PDFs. And so another alternative for you to create beautiful professional PDFs. And you can do that within Quarto as well.

And so same sort of functionality as we talked about before, there are different options that are available to you within the YAML heading that you can change. And then that will change the look of your rendered output. And then there's all sorts of things that you can do to continue to tweak your documents. So for example, this is a types block, which adds a block to change an appearance of a block. So in here, it's filling it with, I think, a certain color. It's putting a radius around it and slightly rounded corners and so on.

And just like Reveal.js presentations, if there is a particular PDF format that you find yourself using repeatedly, you can go ahead and create a template that you can reuse over and over. These are some that are provided by the Quarto team, and the community has also built a lot of types templates as well.

Exercise: callout boxes and format switching

All right, so now let's go ahead and try a few of these things out. So I mentioned earlier the idea of divs. So the first exercise is to add an important callout box to that key findings at a glance. And you can see the code here. And then try changing the format, change it to Reveal.js, change it to types, and then preview and see how things change. I did add a note. There are those specific formatting options that I put for HTML, the code fold, the cold summary, and the embed resources. So Reveal.js, because it's for presentations, it assumes that you don't want to see code. So if you want to see code, you have to explicitly say, show me the code. And so it's a bit redundant to have – or I'm sorry, like these won't necessarily work. And then similarly, types is PDF, so it doesn't allow for code folding and things like that. If you change the format and render, it won't cause any errors. But I do think in real life, it's probably worth tidying up your documents and removing those so that, you know, like your document is a bit cleaner and things like that. But for the purposes of this exercise, you can leave them in. All right, I forgot to add a timer, but I will say let's do three minutes. And if there are any questions, I will start answering them.

So somebody asked for the link of the materials. So it is linked on the bottom of the slides. I also am putting it here. And the PositCloud link is on the bottom of this particular slide, because it's an exercise. Okay, I see there are some really great questions.

One question is, when using WebR, does it load the required packages every time the QMD report runs or only once before rendering? So there are a few options with WebR. So if you anticipate, say, like somebody – like you want to get somebody up and running with your WebR document very quickly, you can pre-install the packages in that, like when they open up their webpage, it will immediately load all the packages that you'll use for, say, your exercise. So when they run the code chunk, they can – they will already have it available, kind of like PositCloud. And so, however, if you would rather, like, have it on an individual basis, because as you can imagine, pre-installing those packages will – might take a while. Maybe they'll do things out of order or things like that. It kind of – it works like an R script. You can have an install packages within your WebR chunk, and then it installs it right then and there. So you have a variety of options.

We have a question, how can I publish Quarto dashboards as a website? So there is a section on publishing if you want to skip ahead and check it out, but there are a few different options. So Quarto dashboards, the output, if it doesn't have any shiny components, is an HTML file. And so you can publish it the same way you can publish a Quarto website, a Quarto webpage or things like that. Today we're going to be trying out PositConnect Cloud, which is one option that allows you to – and we'll actually be publishing a Quarto dashboard too. If your Quarto dashboard has shiny components, then it's slightly different. It will require a server. So it would need – so PositConnect Cloud also allows you to deploy shiny apps. You would need something like shinyapps .io or something like that, or PositConnect if your organization has PositConnect. But it will be slightly different than if it's just purely HTML.

There's one question, for slides that will be PDFs, is it better to start as HTML than export as PDF or develop slides with types? I think it probably depends on how you want to present it. So there is an option, if you see here, to export your Reveal.js slides as PDFs. I wonder what happens when you click it. So you can see what this looks like. So, of course, it won't have any of that interactivity that we normally see in the web-based version, right? But this is something that I can share with my group and things like that. I would say types is – please, if anybody disagrees with me, let me know. But I think types is more for, like, PDF documents, like if you are – well, actually, I take that back. There is a very good types extension. I'm sorry. If I have a chance, I'll try to find it. So I think it really depends on what you're interested in. So if you really want to use types and prefer to do it, you could do that. If you – all you are doing is what I just showed, like you want to just share a copy of your slides in PDF format, like you could do that through Reveal.js too.

Just running through the questions really fast. Can you do parameterized reports similar to our markdown? Yes. I think Libby shared some of the resources from J.D. Ryan, who does really amazing talks on how to use parameters with Quarto. And it's – yeah, it's really, really impressive, like the sort of projects that she has done and shown with parameters in Quarto.

Quarto dashboards

Okay. If I missed any questions, just let me know. But if not, I wanted to really quickly talk about dashboards. We just talked about dashboards. I mentioned Shiny Components. So just to clear that up, this is another format for creating dashboards from Quarto documents. And the idea, if you've seen a dashboard, is put visualizations and tables and text together. Releasing Quarto 1.4. So if you don't know what version of Quarto you are on, you can run this command in the terminal and then find out. And if you have Quarto before 1.4, unfortunately, dashboards won't work and you'll have to update your Quarto version.

And here are just some examples from the Quarto gallery of different kinds of dashboards that you can create. The idea of putting rows and columns and value boxes and multiple pages on a dashboard for your stakeholders. Another example here, we have a sidebar now. So to provide additional information or to add some inputs or things like that. You can add interactive leaflet widgets or HTML widgets if you have used that. So if you visited this dashboard, you can move the map around and zoom in and things like that. And as I mentioned, you can also use Shiny if you need something within your dashboard to dynamically change. So in this case, you can filter by different species, by different islands, and then all the graphs will update based on your filters.

The basic idea is that dashboards are composed of cards. So they're the basic building blocks of your dashboards. You usually don't have to manually define them. Quarto will just pick them up. That being said, you probably want them to be displayed in a specific way so you can organize your content, arrange them into rows and columns. And then you can add additional things to control the general layout of the page, like additional pages, tab sets, and sidebars for something that's a bit more advanced. In terms of what this looks like, as you can imagine, you change the format from HTML, from Reveal.js, whatever you were working with, to dashboard. Here we've added a plot. When we render it, we don't have to define the card. Quarto will assume that you want that in its own card. And when rendered, it will end up looking like this. So we have the title at the top, a single card with our plot. From here, we can continue doing things like adding additional cards, additional content. So here now we have two code chunks with two different plots. Rendering that, we will get our two cards. Now we could do things like add a title so that we can distinguish one plot from the other. So rendered, now we have plot one, plot two, above their respective plots.

So by default, cards are laid out in rows. So one row plot, second row plot. And here I have in the YAML heading, just like explicitly defined, this is the default, but this is what it would look like. But we do have another option. If we would prefer the orientation to instead be columns, we can change rows to column in the YAML heading. And when rendered, now our dashboard looks like this. It's up to your personal preference. We can also use headings to arrange cards. So here we're saying, make a row with these two plots, a single row with these two plots. And when rendered, it looks like this.

Now let's add two rows. Here I put a row with some text and then the second level heading down below. And try to imagine what you think this is going to look like. So I'm going to add a heading down below and try to imagine what you think this will look like when rendered. And this is what it looks like. So if you notice, it put the text in its own card and then created a second row with the two original plots.

And from here, we just continue adding to our dashboard to make it look the way that we want. So here I've added a third plot. So one row with the text, another row with three plots. You could add columns within our rows if we want to be even more specific. And so now what we're saying is within this row, make one column with the first two plots, make another column with the third plot. You can add tab sets to put content in different tabs. So now those first two plots are within one card, but in two separate tab sets. And the third plot is in the same row, but not in the tab set. And so this is what it looks like.

As mentioned, you can continue to customize your layout. If you add a level one heading, this creates new pages in your dashboard. So now I have page one and then page two. And then page two. Page one has the first two plots, page two has the third plot. Looks like that.

You can add logo and buttons to your navigation bar. So there was a question earlier, can we add logos depending on your output? The answer is yes. This is how you would add it for dashboards. So here in line five, I've added a logo. And here I've added navigation buttons to Reddit and GitLab. And rendering it, we can see what it looks like here. Just to zoom in. Now I have a car logo in the top left, and I have the GitLab and GitHub icon on the right, top right.

As mentioned, cards have these fundamental units. And so in terms of what it could be, cards can be text, and it could just be markdown text like we've been writing. We can also explicitly call something a card by putting this card div around whatever we want. And in this case, it would be one singular card as opposed to automatically putting them into different cards. If you have any text that's at the top of the dashboard, it's going to be included with no card styling.

You could do things like add JavaScript-based plots like Plotly or just, you know, standard raster-based plots like ggplot2 . You can also set the size dynamically within the code that you want to use. You can also set the size dynamically within the code chunk option in the code chunk.

You can also, another card option, so we've talked about text, we've talked about plots, another one is tables. So now here I have a dashboard with one card that's going to be a table, another card that's going to be a plot in a single row. And so when rendered, this is what it looks like in the title up above.

Another important component of dashboards are value boxes, so the really big, you know, displays of numeric number or dates or, you know, some sort of thing that you really want to call out. You can build that within Quarto dashboards as well using this div called value box. In this case, I put last updated in a div. You can also write value boxes within code chunks by defining them as content value box, and you may want to do this if you want to refer to anything within your code. So in this case, I am referring to a value within mtcars itself, and therefore I want to use R code for it. So to do that, I need to do the code chunk, I need to specify that it's a value box, and then I also have to use this list syntax in order to specify the icon, the color, and the value of the value box. You don't have to include all those things, but if you want, you know, your value box to look a specific way, you would add it like so. So rendered, it looks like this. Just zoom in. Now at the top, I have my value boxes with the last updated. It hasn't taken a while, and the number of cars, in this case, 32.

And there are different ways to lay out, like, inputs in a dashboard. People often want to filter, want to click a dropdown, and things like that. You can do that with sidebars. You can do toolbars for a horizontal panel, and then also you could do card inputs for card-specific inputs. But let's just highlight the sidebars for today.

consider using Shiny, which if you have not heard of before, is a super powerful, super awesome way of creating web apps in pure R. There's also a version for Python, so you do it in pure Python, so you don't have to know like HTML and JavaScript and CSS and things like that.

And this is actually how I primarily build dashboards back when I was building a lot of dashboards. The only thing is, as I mentioned earlier, there's slightly different deployment methods for Shiny that you have to consider. In addition, Shiny has its own syntax that you just kind of have to get familiar with if you're interested in using it. So as mentioned earlier, a great way of building web apps with R. And within Quarto dashboards, you can include embedded Shiny components to add that interactivity. So here is our non-interactive dashboard with a sidebar that's empty and a column with two rows. Here's our sidebar, and this is what it looks like. And then down here, we have a plot, which is from the empty cars, which is a built-in data set showing the miles per gallon. But say, what if I want my stakeholders to be able to switch between different variables? I want them to be able to look at a horsepower and things like that.

So now I can add my interactive components. So the first thing is within the YAML heading, I have to specify that it's server Shiny. I also have to add this context setup chunk. If you haven't used Shiny before, this syntax will look familiar. If you have not seen it before, this is kind of what it looks like. You have to specify for Shiny the UI components. So what does the person actually see when they open your dashboard? And then the server components,

like what is actually happening in the backend? So in this case, I'm saying create a way for the user to select a new variable. It's going to say, choose a variable. And then it's also going to provide the column names from the empty cars data set as the various choices for the person. And then down below in the main body of the dashboard is going to be the result of that.

So a plot that is going to render based on whatever variable was chosen in the sidebar.

And then I have to explain to Shiny what to do. So in this case, filter the empty cars to select just that one column and then plot it.

And putting that all together, now we have a dashboard where we have a sidebar with a drop down. That drop down offers up all of the different options for empty cars. And then whenever somebody selects a new variable, the plot in the main body gets updated.

So I have added a dashboard.qmd file in the exercises. You can go ahead and render it. I did change it up a little bit from the original exercise one. If you want to see what ends up happening if you change the format of that first exercise one, please feel free.

But if you would like to play around with one that's more optimized for the dashboard format, you could do 01-4.qmd and feel free to change things up. I might lower this a little bit just so that we can get to the theming, which I think is a pretty fun part of Quarto.

But again, all the resources will be available for you in the future.

So there's a question, is Quarto now supported on Shiny server? If anybody knows the answer, please let me know. But I have to admit, Peter, I don't know. I will have to check.

One question is, if I change the working directory in one code chunk, will that change persist for the next code chunk? Or do I need to start again? Oh, Olivia, I saw that you referenced, or I'm sorry, you answered that. Thank you.

Can Facetwrap be integrated in dashboard? So each section, each will be a section of the dashboard. I think you might be referring to Facetwrap from ggplot. I don't know if you can do it directly from a single ggplot plot, but I would say probably what you can do is set up different cards depending on the different views that you want from your Facetwrap. Alternatively, you can create a single card that has all of your plot with all of the different wraps that you want.

Another question I don't know, can I set to fit with and hide programmatically depending on the input? I don't know. Thank you for these great questions. Oh, somebody's answered. Oh, thank you. I learned something today.

So there's a question about relative paths. And so I think, and if you know the sort of the syntax of like, you know, dot dot returns you to the previous folder and things like that, you can use that kind of syntax to enter different folders if your images are in different places.

So for example, this Quarto website that we're looking at right now for the workshop, everything is based on the root directory, but all of the slides and exercises or everything are in individual projects. So if I want to refer to the images that is in my root directory, I have to do period period slash and then images slash and then the name of the images. So that lets Quarto know to go back to the root directory, go to images, and then find that specific image.

So that is definitely possible.

Quarto projects

All right. Well, thank you, everybody. So I'm going to talk about projects very, very quickly so that we can get to, again, the really fun stuff. But the idea behind projects, is so far we've been working with standalone documents. So a web page, you know, an HTML file, a dashboard, revealjs presentation, and the types document. However, sometimes we want to work with Quarto projects, which I think I just alluded to, the directories, and they provide a way to render all of your files in a directory with a single command. And so instead of having to render individual QMD files, you run Quarto render and then the name of your project, and it renders all of them at once.

The nice thing about this is you can share YAML configurations. So in a website, right, you probably want all your pages to look very similar. And so you can specify that within a Quarto project so you don't have to copy and paste it across all of your web pages or something like that. You can redirect outside artifacts to another directory, which you can't do with standalone documents. And then the ability to freeze. And so this is really great if you have documents that take a really long time to run. If something hasn't changed, it will automatically rerun it.

There are some things that have to be projects if you want to create them. So a website, a blog, a book. If you think about it, like they have things that are in reference to each other and things like that. And therefore, if you want to change, you know, your post into a blog, then you have to move it into a Quarto project. And so to quickly know whether or not you're in a project, it's a directory, a folder with files in it that contains a file called underscore Quarto.yaml. So this is a Quarto project. It's a file directory with underscore Quarto.yaml.

And this underscore Quarto.yaml file is a yaml file. So again, key value pairs that give you all sorts of information about your particular project. So this is the one, for example, for this website with a title and then building it out. I have specified I want the type to be a website. I can add more metadata like the description that I want page navigation. And for the page navigation, I can refer to different files within the contents of the navigation bar. So here I'm saying, you know, look into the 00 introduction folder and make index.qmd the introduction and put that in the navigation bar.

And then down below, you can do things like set freeze to auto. I mentioned that in a bit. But say echo true. So I want echo to be true throughout my entire project. So freeze allows you to, you know, specify like re-render these documents, never re-render these documents, re-render these documents only if something changes within the file. And so the idea is to make it like a lot quicker to rerun, especially if you're only changing some things. So if you set freeze as true, it'll never re-render during the project render. Auto means it will re-render only when the source changes.

So just to show really quickly like what you can do. So in the document that we have been working on that has been a standalone document, let's say we want to create a project from it. So I'm going to walk through how to do that.

So here is our Rformat Quarto exercises with all the files. So this is the command line interface in that you have to run it from the terminal. If you've never used the terminal before, in RStudio and in Positron, there is a tab called Terminal that you can open. And so here it lets me know I'm in my folder, and I'm going to run that Quarto create project.

Here I can select the type of project that I want. So I'm going to just do website. I'm going to call it Rformat Workshop.

All right. So now it has created a new project with these files. And then if you notice, in any case, this is how to create a new Quarto project. So as I mentioned earlier, it's going to be a file directory. There's an underscore Quarto.yaml file that specifies that it's a website that, you know, what's contained in it. From here, I can build up that navigation bar. Here it's saying for the HTML format, use these themes, add a table of contents, and so on. So you would edit this depending on what you want to create for your website.

So I really want to get to theming. But again, if you are interested in creating a website, a book, a blog, then you need to create a Quarto project. And that command line interface allows you to do that from the terminal. And then you can specify what is it that you want to create.

Theming with brand YAML

So now let's get to the idea of theming. So this is you have created your Quarto document. It's fantastic. It has code. It has text and everything. But now we want it to look the way that you would like it to look. So for that, we can add themes through theming your Quarto documents.

There are a few built-in themes. So for HTML, for example, Quarto includes 25 themes from something called the Bootswatch project. So changing the theme to any of these will automatically change, once you render, it will automatically change your theme to look whatever the theme specifies. To do so within your YAML heading, you would add theme and then the name of the theme that you want. And that is a quick way for you to create a different looking Quarto document from the default whenever you want.

However, there is usually an organizational theme, you know, for companies, for our, you know, whatever we're working with, that we would rather use. And so here, for example, is the Art Farmer one. You can see it uses this font called Source Sans. It has blue headings that are like a little bit bolder. You know, the font is actually this gray and it's not black and things like that. So what if we want to apply our organization's theme to our Quarto documents?

So there are a few ways of doing this, but the one I want to introduce today is one called Brand YAML. And the idea behind Brand YAML is a portable YAML file, and we've been talking about YAML a lot, and it basically codifies your company's brand guidelines into a format that can be used by Quarto, by Python, by different R tools to create these branded outputs. And the idea is to support unified branding theme for these tools. So your web applications, your printer reports, your dashboards, your presentations would all have a consistent look and feel.

company's brand guidelines into a format that can be used by Quarto, by Python, by different R tools to create these branded outputs. And the idea is to support unified branding theme for these tools. So your web applications, your printer reports, your dashboards, your presentations would all have a consistent look and feel.

Brand YAML is relatively new. Right now it is supported in Quarto version 1.6 and above for the specific formats of HTML, Dashboard, revealjs, and Typed, all formats that we've talked about, coincidentally. It also is supported in Shiny for Python . And if you upgrade to BSLib 0.9.0, it's also supported in R Markdown and Shiny for R.

But today we're going to focus on Quarto and Brand YAML. So Quarto offers probably the deepest integration with Brand YAML. The idea is if you have an underscore brand.yaml file in your project, Quarto will automatically apply the branding that you've specified across all of these output formats, Dashboards, revealjs, Typed, and HTML, so that you have that brand consistency from that single file. So in fact, the website and the slides that you see today, they're being formatted by Brand YAML.

In terms of how it works, you create this single underscore brand.yaml file and you save it in the root directory of your Quarto project. And if it is a project, sorry, you can also do it for standalone files, but if you have a project, wherever your underscore Quarto.yaml file is, it's also going to be, you want to save it there. This is how Quarto will automatically detect its presence and then apply the brand to all documents of supported formats in the project.

In terms of what it looks like, it's organized into five key sections. Each one is kind of like a different building block, but each one is also optional. So you can make this file as simple or as complex as you need. The first is meta, which is the identifying information, the metadata of your company, for example. The other one is logos, any logos that you use. Color, so the colors of your brand guidelines. And then typography, so the different fonts for the different elements in your documents. There is also defaults, which allow you to be even more specific about different details. So this is if you need further customization for your brand.yaml file, but I would say the first four are probably the most regularly used because they cover like a really wide swath of things.

I would also say brand.yaml is meant to provide like good enough branding, as in it's not going to be super, super specific. If you need extra customization, we have a section on that that we'll talk about, and you can definitely do that with Quarto. But for, you know, say getting 80 percent there, brand.yaml is a great option.

Brand YAML sections in depth

So here's my underscore brand.yaml file with my different elements, just the keys, and then I can start peeking it in. So this is what a populated one would look like. And so here we define our metadata, our logo, and so on. So here is our meta, our logo, this is what color looks like, and then typography are the fonts.

And the idea, another idea behind brand.yaml is that it's meant to be like easy to share and easy to read. So ideally, you know, one of your colleagues picks this up, they can take a look at your brand.yaml file and kind of understand like, oh, okay, these are the colors we're going for, here are the fonts, and so on.

Just to really go deep into each of the different sections, so the meta section is for key identity information. These don't really change, these don't change the visual output of your document, they're just for reference. So particularly, like say you have different style guides for different reasons, or your style guide changes over time and things like that, you can add that information here. So here you have the name and the link, you could add multiple links if we would like, like our company's social media. You can continue adding onto this with even more detail to centralize that key brand information. And if your company like ours has like a long and a short name, you can add that too.

The next section is the logo. So you specify your brand's logo at various sizes, you can provide just a path to a local file, or you could do a relative one to the brand.yaml file, or use a URL. So you can add, or I'm sorry, define logos for different contexts, so like small for tiny displays, the medium one for website headers, and large one for presentations, or so on. And brand.yaml also supports dark mode, so if you need different logo versions, because you want to provide light and dark mode, you can do that as well. So here's light, here's the dark version.

And then you can continue adding logos, you can also give them like descriptive names, so that they're a little easier to reference in your documents. So here I have specified the header logo as header, and then I'm referencing it in my light mode as header without having to copy and paste that URL. So you can imagine this is very handy if, say, the URL changes, you just have to change it in one place and not throughout your document. And you can do things like add alternative text as well, like so.

The next step is color. Probably the part that I find the most fun, and so there are two main parts. The first part is the palette, where you name colors specific to your brands, so like black, and then if there's a specific hex code, blue, and so on. And so this way we can reference these colors by names without having to memorize the hex codes. And again, if, say, your blue changes, you just have to change it in this one place. And then the second part is where we assigned our brand colors to the theme colors, so now they have like a role. And Quarto and Shiny would know what to do with this information. So foreground stands for main text color, and it's going to use black, and so on. And so you can set different colors for things like warning, and danger, and so on. And then you can reference that in your documents however you see fit.

You can also give it that name that you define up above in the palette, or you could just use the hex code too.

So this is the full section, so this is what it ends up looking like if you wrote everything out with the colors and their roles. Yes, and you can reference them in the different sections as well. So here, primary is blue, and blue is that hex code. But you can also just keep it simple if you want. That was probably one of the more complex examples. And then you can continue adding to have that flexibility later on.

And then the next section is typography, which is fonts and their styles. And very minimally, you can just do the base font. So for like most of your text, your heading and monospace, which is anything that looks like code.

And then this one is just like the last one, but it's just a little bit more explicit as to what's happening. You can do things like add fonts from Google. So here, I'm saying open sounds from Google, Roboto Slabs from Google, and so on. So that Quarto knows where to find that font if it's not installed on your computer. And a neat detail is you can also specify bunny. And bunny fonts is a GDPR compliant alternative to Google Fonts, which if you need that for data compliance requirements, you can add that.

If your brand uses proprietary or custom fonts, you can also include them locally. So you would set the source to the file and then list each font file with its path. And so even if they're local, you can add those in brand YAML as well.

And once they are defined, you can map them to the different text elements. So base is, for example, the font and appearance for the base or body text. And so that way, brand YAML knows what to use these different fonts for. Roboto Slabs will be headings and so on.

But you can go even deeper. So say you want to do things like specify text size, line height, font weight. You can use one or more of your defined theme colors from before to set, for example, in this slide deck, I have set the dark blue to the heading for these presentations and so on. So you can really, really keep adding. Another thing I did for this presentation is use like a heavier weight for the headings. That's why it's a little bit thicker. And here is an example of referencing the color from up above for your typography.

And just to talk really briefly about default. So there are a ton of BSLib theming variables that are available. Here's 932 with a ton of options for you. And if there is a specific one, say you are creating a dashboard with a navigation bar and the default color is white, for example, and you want it to be blue, the specific blue that's in your brand YAML file, you can actually go ahead and add that in your brand YAML file. Here I'm saying my default for the navigation background, which is a bootstrap variable and make it the dark blue that I had to find up above. It does have the specific syntax of using a dollar sign, brand, dash, and then the name of your font. But that way, again, if your dark blue changes, you don't have to change it for your navigation bar. You just have to change it where you have to find it.

And so in terms of using it for Quarto, because of that deep integration, there are a few things you can do. Like if you're writing a Quarto document and you want to add your logo somewhere, you can use this short code to do so. So here I've added the Art Farmer logo. If you have noticed, some of my slides are different colors than others. And for those, I'm also referencing a color that I specified in the brand YAML file using this syntax, the background color, which is from Quarto, and then using the short code to say make it my primary color. And so that way, again, you just define your brand file in one place, and then you can use it throughout your Quarto documents.

If you don't want to call it brand YAML, underscore brand dot YAML, I mean, the file, you don't have to. You can change its name, but you would have to refer to it in, or if it lives in a subdirectory, you would just have to add the brand key to your YAML heading, so that Quarto knows where to look. And so there's a specific file in your Quarto project that you're not interested in having with your brand. You can also specify brand as false.

All right. So in the workshop repo, there was secretly a brand YAML file. It's called 03exercises.yaml. Rename it to underscore brand dot YAML, and then re-render your Quarto document. You know, one thing you can do is you can change the variables in your brand YAML file and re-render to see how your theme changes. Another thing you can do is, say, change your format from HTML to revealjs to types and re-render so that you can see what it looks like in different formats as well. All right. So two minutes to do that. I will check the chat.

So one question is, what if the font has to be downloaded first because it's not available in default? So you can say it's in your Quarto project. Download the – I think it's W-O-F-F file or the different – you know, the font file. Have it available somewhere, and then you just specify it in your brand YAML file, the file path to that particular font file. You just have to be aware if you're sharing your brand with somebody else that they would also need that file if they want to use that same font.

For anybody who's just joined us, the workshop link is down here. We are in the theming section. This is about wrapping up, too. The theming section, not the workshop.

Somebody asked, can I change the headers from the main document, too? If you mean specifically in the brand YAML file, yes. In the typography section, you would specify what you would want for your headers, like the headers that you see. My slide, for example, have brand YAML applied to them, and we'll talk in a little bit what if we need even further customization, like say we want our header one to look different than our header two, which we'll talk about in a second.

One question is, can we specify colors using HSL or HSB instead of hex? I don't know. At least all the instances I've seen have been hexed, but I will find out.

It's such a great question. Thank you. How did it go? Was everybody able to change their file to underscore brand.yaml and re-render? I hope it changed. Yay, great.

Somebody shared earlier, like how can we publish these, share them with others, so that we don't have to go back and re-publish them again. We publish these, share them with others. There are a lot of different options in terms of how to do so. If your Quarto document is a static HTML page, you can host it on anything that can be

deployed to a web server or web host, so GitHub Pages, Quarto Pub, Posit Connect. These are very common ones. The ones I want to talk about specifically is Posit Connect Cloud, which is, again, another relatively new product from Posit that allows you to deploy a variety of different apps, like R Markdown, Quarto, Shiny, Shiny for Python, Streamlit, Dash, all sorts of things. If you go on the website, I'll show you how to do it. It will share the list of all the different options. Personally, I really like Posit Connect Cloud. It being cloud-based, of course, this means that if you need some privacy settings or something like that, there are different plans available for that. But if it is to openly share something to the world, like, for example, this workshop website, you can use that as an option as well.

If you want to give it a shot, you can sign up for a free Posit Connect Cloud account at this URL. And once you have done that, you can sync with Connect Cloud by running this RSConnect Connect Cloud user function. And what that will do is pop up a new page. Actually, maybe we'll just do it together so that way we can move on to the next slide. Because somebody asked, can we use both brand.yaml and style.css together? Does one take precedence over the other? The answer is yes. So I'll show that in a second.

Let's see if this allows me. If you want to give it a shot while my project opens up, feel free. But essentially, this will allow you to, say, deploy that dashboard that you have been working on to Posit Connect Cloud. And then you can share it with others.

And then the next thing I'm doing is running this to deploy the dashboard.

So this is what my dashboard looks like. It's now available in Posit Connect Cloud. Here I can change different settings. Like if I want to change the name of it or if I want to share it, I can copy this link and share it with everybody as well.

So that's one option for publishing. I just wanted to share it. And the ability to publish directly from RStudio is very new. And so I think it's very, very exciting too.

Using brand.yaml and sass together

And because we got asked this, I will skip really quick to extra customization. So the question was, can we use brand.yaml and style.css together? The answer is yes. And so just go through the slides really quick. As I mentioned earlier, you do have the option of defining light and dark, both for your fonts – or I'm sorry, for your logos, but also, say, within your color as well. And so that way, your document, your website, and so on, would look different depending on how you define it in your brand.yaml.

So there are these variables called sass. Somebody mentioned css. That's an option as well. So these allow you to really customize and tailor your document depending on what you need. And so the nice thing about sass is it's a very human-readable sort of way of writing it. Linked in the bottom are the variety of sass variables that you can edit within Quarto. But for example, like, say, body background, this is what the sass variable would look like. So I would add that in my sass file. And then the color that I would want to assign to it. And that's it.

You can do specific fonts. And so code blocks. So here you can add a code block border, code block background, if you want it to be a different color than the default. There are a ton of variables. And so when you find yourself really needing to tweak something, definitely first take a look at the documentation and see if there's a sass variable that controls that and try to edit it as well. In terms of what your .scss file looks like. So this is where you would put your sass variables. This file is called styles.scss. At the top, you can define functions. You can define defaults. And so these are using these sass variables that I just mentioned. So in this case, I'm saying for heading two, use font size 1.6. You know, for headings, font weight, use 500 and things like that. So brand yaml is supposed to get you mostly there.

And so say brand yaml gets you mostly there. But if you need that extra customization, you can do that in these sass files. And then within rules, you can add like even more things. So here's specifying all the different headings and that I want to add a text shadow and things like that. If you just have a sass file, like you don't aren't using brand yaml, you can specify it in your yaml header in, you know, in your underscore Quarto that yaml file or within individual documents like so. But you can also use it together with brand yaml. So if you're already using brand yaml, you can use sass to further customize your theme. So like things that brand yaml is just not able to do, add drop shadows to cards, specify the color of block quotes, set different header levels to different colors and so on.

So here, for example, they still talk to each other. So within a sass file, you can still reference things within your brand yaml file. So say, you know, you want your header one to be the blue from the brand yaml file, the header two to be the green, and you can refer to them like so. So that way, you don't have to include hex codes or anything like that within your sass file unless you need to. So to answer the question, in this case, the sass file has priority over brand yaml. So it will override whatever you have put in your brand yaml file.

So to answer the question, in this case, the sass file has priority over brand yaml. So it will override whatever you have put in your brand yaml file.

But they will, you know, for everything that's not defined in your sass file, it will defer to your brand yaml file. And so here, you can see, you can change the order. So in this case, your sass file takes precedence than your brand yaml file, and then Cosmo, which is a built-in bootstrap theme for Quarto for everything else.

Oh, sorry, I thought I added this, but that being said, you can rearrange this. So say, you want Cosmo to take precedence over brand, you would just switch them in your order.

Oh, and I mentioned earlier that you can add defaults to your brand yaml file as well. Okay, so I just wanted to make sure to answer that question. It's a very good one, but yes, everything should work together. So for example, in these slides, I have a sass file just for, you know, these little blocks, and everything else is determined by the brand yaml file.

In the last 10 minutes, I just wanted to talk about creating and sharing your brand. So you have created a brand yaml file. It looks awesome. It looks like, you know, really great. But then you want to share it with your colleagues, right? There are a few different ways of doing that. It's a yaml file. So you can, you know, just send it over, you can put it in, if you use something like GitHub for version control, you can add a creative repository for it, and share it that way. The benefits of that is if something changes, right, somebody can, you know, quickly reference like, whatever has changed and use the latest and greatest file.

And since we're creating a brand yaml file, to create any yaml file, you can start off with a plain text file. In RStudio, you could do file, new file, text file, and then start building it out from there. The only thing that will make it a yaml file is whatever name you choose, or the extension you choose, so you can save it as underscore brand.yaml, and then you have a yaml file. If you go to the brand yaml doc site, there is a page with inspiration, which shows different brand yaml files for different organizations. So if you want to take a look at Posit's, for example, and kind of use that as a reference for your own companies, you can do so. There is also an article on the brand yaml documentation, if you would like to get help from a large language model. So it provides a prompt that you can add, or you can give to say, ChatGPT, that lets it know like, what is a brand yaml file and how to structure it. And then you could give it some inspirations and references and things like that, so that it can help you start building your brand yaml file. And then you'd copy and paste that into the file that you just created.

There is another relatively new thing, lots of relatively new things. As I mentioned, you could do a shared repository like, or GitHub, if your company uses Google Drive and things like that to share your brand yaml file. But in Quarto 1.8, there is something called a brand extension. And so this, instead of you having to go file, new file, you know, open up a file to create an extension, a creative brand yaml file, you can run Quarto create extension brand in the terminal and give it a name. And then it will provide, you know, all the boilerplate like starting materials for you to create your brand yaml file. One thing to note though, is right now, brand extensions must be used within a Quarto project. So if you have standalone files, this won't work. But I know the team is working on alternatives for that.

So this is what it looks like. If you run create a Quarto brand extension in the terminal, it's going to populate a folder with all of these files. And then it's going to ask you where do you want to open this and you can say Positron, VS Code, RStudio. One of the key files is going to be this underscore extension that yaml file. And this just lets Quarto know, hey, we're using a brand extension. And from here you could do things like change the author, you know, add any metadata that you need. And then the other important file is going to give you is this brand.yaml file. And from here, this is where you start building your brand yaml file.

There is also an examples document. So you can change your brand yaml file and then re-render that document and see how it looks until you get, you know, exactly what you want. And then once you publish your brand extension to say GitHub repository, anybody can add it to their Quarto project by running this Quarto add command. So say I have a website, I want to use your brand extension. I would go to the terminal and run Quarto add and then whatever the name of your GitHub repository is and then slash and whatever the name of your brand extension is. And then that will basically download that folder into my Quarto project. And the next time I re-render my Quarto project, it will have all of your branding. And then any time that you make changes, you, or I'm sorry, if any changes happen to your brand extension, you can run Quarto update and then the name of your brand extension and that will update it in your project as well. So that way it is always, you know, the latest and greatest.

So I think we have three minutes left. So if you would like to try creating a new brand extension, I do recommend doing it locally. Otherwise, they'll put it in the folder that you've been working on. And then you can, you know, try it out, at least start to create your organization's brand so that you can, you know, hopefully share it with others and use it for your outputs as well.

And so that's all the material I have for today. Happy to take any questions. That's all the material I have for today. Happy to take any questions with the remaining time, but if not, again, thank you all so much for being here with me. Reach out if you have any questions or would like to chat.