Transcript#
This transcript was generated automatically and may contain errors.
Thanks everyone, I'm Megan Hall, really excited to be here today to talk to you guys about Quarto Template.
I have been lucky enough to be a member of the R community for a while, maybe we are friends on Twitter, formerly known as Twitter, maybe you've seen me speak before, maybe you've seen my blog, but I also do a lot of things besides R. I like to cross stitch, this is old, I need to make a new one, this is obviously the old type. I also like to bake and cook. I like to do yoga, if there's any Peloton people here, shout out to the Peloton people. I love to read, especially anything in kind of the mystery thriller-ish genre. I have a baby who thankfully also enjoys reading. I work at Zealous Analytics, which is the greatest sports analytics company in the world. I am the technical product manager there of the NHL group, meaning that I kind of help our NHL clients make sure they get the most out of NHL tracking data.
So that's a lot of things, like I'm a fairly busy person, I do a lot of things, and I'm really excited to be here today to tell all of you that I have figured out the secret to doing it all, and that's saving time with Quarto Template.
What is a Quarto template?
I'm assuming if you're here, I don't need to actually sell you on the benefits of Quarto if you're in this session, so I'm not going to waste time doing that. But if you're thinking, what is a Quarto Template? I stole this straight from the documentation. A Quarto Template is a straightforward way for users to get started with new Quarto projects by providing sample content and options.
So a lot of the content that you'll see in the Quarto docs, especially about Quarto Template, is mostly about public Quarto Templates, things that people, things that wonderful people in the R community have shared and created, and that you can use on your own, shared through GitHub repos. But today I'm mostly going to focus on private Quarto Templates. You're working for an organization, you have some Quarto Templates that you want to share with other people that you work with, but you don't want them to be really available in like public GitHub repos, because we had to figure out how to do this at my organization, so I would like to share it. I feel like it's probably a pretty common use case.
Why bother creating a Quarto template?
So first question, of course, is why do I bother creating a Quarto Template? Mostly, it ensures that all the documents that are produced by your organization using this template have a similar style and structure. David talked really nicely about like why design matters. I am extremely on the side of, yes, design matters a lot. I'm the person annoying all of my co-workers, and I'm like, that needs to look nicer if we're going to send it to a client. The design and presentation of things, graphics, reports, it matters.
And we have, again, in my organization, we use Quarto a lot. This is an example of a white paper. We also use Quarto for like release notes. We have scouting reports, and player reports, and post-game reports. We have Quarto all over the place. And so being able to have the Quarto Template allows us to really specify the structure and the style of what they look like. Everything from kind of how our tab sets look to how the callouts look, all of that always looks the same. Make sure that our clients always have like a streamlined look.
It also saves analysts from having to learn and implement HTML and CSS. Just by giving them a starting point of a Quarto Template, they don't have to worry about that at all. It also provides a nice skeleton to help set people up for success. You can kind of create with the Quarto Template, you can, of course, focus on the styling and more of like the scaffolding of what you want people to see through the style of the Quarto Document. But you can also provide a lot of sample content that might be useful for your analysts or whatever, whatever people in your organization are going to be using this template.
As an example, as one small example, this is just a small snippet from our Quarto Template. We make sure we install our internal packages that we use. We install, the template installs the fonts that we use. Make sure they're using the appropriate hex code for zealous green. Don't want any unruly greens out there. And this is what our template looks like when it's fully rendered. This is just the plain straight out of the box Quarto Template without any, without the user or the analyst doing any kind of work on it. And so, yes, again, it has the styling that we want. So the people making the, actually doing the analysis don't have to worry about that. But it also gives examples on how to use our custom ggplots and how to use our custom gttheme and anything else that we want to give them, how to query data. We use a lot kind of with video and embedding video and making sure that our analysts know how to do that appropriately.
Again, by putting this example content kind of right where the users need it and use it, saves everyone else time for having to kind of answer these same kinds of.
It also lowers the lift for write-ups. Again, maybe make it easier and people might do it. Again, we use a lot of this for external reporting, but we also, we've gotten people to use it for kind of internal white papers, project updates, stuff like that. As much as you can kind of do the work for people in advance, again, make it easier and they might actually do it.
Customizing Quarto reports with CSS
So how do I make this? You can do an entire session or an entire workshop really on customizing Quarto reports. They're nearly infinitely customizable. CSS, HTML, again, you can go, you can go really wild with that, which is great. But today I'm just going to go through a couple, just one example from our report with a couple of tools that I like to kind of encourage more exploration into learning more about CSS and how to further customize your Quarto reports. Because a good starting point is to just start tinkering with some custom CSS files that you can put right here in your YAML.
So this is one part of our Quarto template. This is at the beginning of all of our reports, just saying this is confidential. It's not for distribution. In the template itself, it looks like this. We have this custom confidential div, just says confidential, not for distribution. So this is what it looks like in the QMD file in our template. And in the theme file, this is the CSS that makes up that banner. It's a pretty simple text box. It's got white centered text. We've specified the background color and the font. And border radius is the element that kind of rounds the corners of your text box.
But if you're just kind of starting to dip your toes into CSS and you're trying to learn how to customize all these Quarto documents, you know, you might be thinking, well, how do I know that that's the element that rounds the corners of the text box? So one trick that I really like is DevTools. I'm talking specifically in Chrome, but other browsers also have their own equivalent to that. So in Access DevTools, if you have any webpage or any rendered HTML document or a Quarto document, just right click and hit inspect. And that will pull up basically the entire style skeleton of that HTML website, Quarto document, whatever. You can hover on the left, just kind of move your mouse like normal. In this screenshot example, I'm hovering over our confidential banner.
The pane on the right will show, again, the page skeleton and where it fits within the page. And then at the bottom right, it actually shows all the styles that are applied to that element. So the very bottom section there on the right is exactly identical to what's in what's in our theme file. So using the DevTools is really nice for exploring. I use it all the time when I see examples that other people share of Quarto documents and I'm like, how did they do that? I just right click inspect and you can see all of basically the entire skeleton of their page.
I just right click inspect and you can see all of basically the entire skeleton of their page.
Has been really helpful to, again, as you're learning more about styling, customizing these Quarto documents, what is even available to customize? How do people know how to do it? Looking at the DevTools through the inspect menu is a really great way to get started. And you can even, when the DevTools are open, you can even change all of those style elements and see how they reflect on the document that you're looking at. Of course, those won't be saved if you want to incorporate those into your Quarto document, you need to go to the source file, but it's really great for kind of experimenting and just playing around to see what changes what.
The other resource I recommend, and again, at the end, I have a post on my website that's got all of these links to it. So I wouldn't worry, no need to worry about remembering any of them. But the other resource I really like is the Mozilla web docs. They have a lot of really great documentation for a lot of languages. I mostly use it for CSS and HTML. This is a sample of what, again, their border radius page looks like for that particular CSS property. And it shows you examples and you can kind of play around to see what different values are. So with those two, even just knowing about DevTools and Chrome and looking at the Mozilla web docs, you can kind of quick and dirty get started with customizing these templates.
Sharing templates via an internal package
All right, so let's say that you have created kind of the skeleton of a Quarto template. You have some sample content that you want to be able to share with, again, other people that you work with. Maybe it's like tips on how to make sure that you're authenticating correctly, getting data from your database correctly. You've got some theme files where you've used some of this advice, some of David's advice, to kind of maybe edit your colors and your fonts that you use. And how do you share it with people? You could, of course, just kind of bundle it up into a folder and email it to people or put it on your share drive. But if you have, eventually you're probably going to want to make changes to that. You're going to want to add things or make updates. It's hard to track who has what version. What version control is a great invention. Also, if you have multiple, you can create templates for multiple formats. So you have a PDF template, you can have an HTML template, template for slide. Having all those things rolling around is kind of a lot. So my number one recommendation is to put it in an internal package.
If you already have an internal package, perfect. Good to go. That's what we're going to talk about. If you don't have an internal package, go read Emily Reederer's post on building a team of internal R packages, which will absolutely convince you of the utility of R packages. She does a great job kind of delineating all the different roles that an internal package can hold and kind of how they act as co-workers. So definitely go read that if you're not quite convinced on the utility of internal packages, and then come back when you're ready to share your Quarto template.
So our example function that I have, again, in my team is just create zealous HTML that lives in our internal package. And this function kind of have to address two things. We have to make sure we have all of those files that we want to give people, right? Our template file, if you have any image files, any logo files, our CSS files. We also need to create a function that's actually going to copy all of those files from our internal package into like our user's working directory.
So for the first one, the files to copy, this is an exact GitHub screenshot from our internal package. All of those files that I mentioned live within the inst folder. I've never heard anyone say that, so I don't know if that's how people say that, but I call it the inst folder. They live within the kind of ext data slash underscore extensions folder. That's kind of the particular notation that Quarto means. And then within that folder, you can have separate folders for, again, whatever output format templates you have. As you can see, we have one for HTML. We also have one for PDF using LaTeX. I have learned this week that I need to switch that to types, so that is now on the to-do list. We also have one for slides. So this is where you would put those static files in the structure of your R package.
And then the actual function that's going to copy those files lives just like any other function in a package in the R folder. And this is what that function looks like. Please do not read this. Like I said, we have a post. Do not worry about reading this. But this function, in essence, does four things. It creates an underscore extensions folder in the user's working directory, which, again, is the notation that Quarto requires where it expects your extensions to be. It copies over all of those files, the logo file, the template file, the CSS file, from the R inst folder in your package. And this function has one argument, really. It's just a file name argument. What do you want your new file to be named? So it creates a new QMD file, again, in the user's working directory with whatever name they want that is R template file just renamed. And then it takes a nice step, and it also opens that file in the editor.
So this will go through a couple times. It's a GIF. So I was having GIF, real serious GIF issues with this. So apologies if it's a little bit blurry. But in essence, all it does is it calls this, again, create zealous HTML. You put in the one argument, whatever you want your file to be called. In this example, it's called sample. And it just instantly copies over all of those files and opens that QMD file. And that template file is completely renderable right out of the box. I showed a screenshot earlier of what it looks like with kind of all the sample content. So it just works right away.
Takeaways
All right. So as I said, all of the content, all of the text of the function is available on my website, Megan.Arbine.io. A few takeaways I have for this talk.
Number one, create an internal package if you don't already have one. This talk is actually just an internal packages talk in a trench coat. This is a great example of all of the useful things that you can put in an internal package. So please create an internal package, even if only to save your ggplot custom thing, which I really hope you have if you're creating a lot of things across an organization.
If multiple people are creating Quarto docs in your organization, consider creating a template. It is a little bit of a lift to create one in the first place. But it will save everyone else a lot of time down the line. To learn more about CSS, again, one of the beautiful things about Quarto that I know I don't need to sell anyone on is how infinitely customizable they are. And learning just a little bit about CSS can go a really long way. I consider myself an absolute beginner when it comes to CSS, but I can still do just enough to know how much you don't know. But I can still kind of get around customizing an HTML or PDF or an HTML document. And then lastly, again, I have saved so much time, I'm just drowning in free time. So please get in touch and find me and send me book recs. Thank you.
This talk is actually just an internal packages talk in a trench coat.
Q&A
In R Markdown, there was some way to register a template and it would appear in RStudio's dropdown options. I forget the details. Does this work in the same for Quarto?
That's a great question. And I don't know the answer. I have seen, it is a thing that people care about because I know I have Googled that before. And I'm pretty sure if you Google it, there is a blog post about it. Because I have seen when I was figuring out how I wanted to do Quarto templates, I saw people. So there are other people that care about that exact question. And I think the answer is yes, that they have figured it out. But I don't know what the answer is. But it is out there.
All right. The next question is, do you have any advice for keeping anything consistent between multiple export formats? For example, HTML plus log type and types?
That's tricky. I hope it will get easier with types because one of the issues that we have for HTML, I don't find a lot of consistency issues like with ggplot going from LaTeX to PDF. Issues with tables, at least historically, we use GT, we have a custom GT theme, doesn't always translate as well in LaTeX. I have to use cable extra for LaTeX, which kind of causes issues. But I've heard, I've been hearing that's way better with types. So I would say look into types because that's what I'm going to be doing.
Next question here, I'm going to apologize for the color of this question, it's so spicy. It says, why use an R packet for the QMD template when it's easier to use the quarterly used template command on a GitHub repository?
I think that's only true if it's public. Because we had to start, we had to kind of venture into this area because we wanted our templates to be private. We didn't want to share them in a public, and I know a lot of, at least when I was looking, when we were doing this earlier at the beginning of the year, most of the kind of online advice for templates was focused on like Quarto add or Quarto use or whatever that terminal command is. And they would only work for public repos and all of our repos are private. So, but maybe there's an easier way to do this and that would be great.
All right. Final question, what are the advantages of picking CSS over SAS to customize the.
Oh, that's a, oh, that's, I said I was beginner at CSS. That's venturing into more intermediate territory. No, I use, we use both like the SCSS, our theme file is SCSS, which uses a lot of the SAS. So we definitely use both.
