Styling and Templating Quarto Documents - posit::conf(2023)

Transcript#

This transcript was generated automatically and may contain errors.

All right, welcome everybody. I will be talking about Styling and Templating Quarto Documents.

Once I realized that I would be the last talk of the day, I decided to employ an alternative, more bust-feat style title to hopefully bring up some spirits. So it's, are you worried about styling taking too much of your time? In 20 minutes, you won't anymore. So that's the general idea of what I will be talking about.

All right, so to set a little bit of a ground floor, I'm imagining that you, all the viewers, you're either a Quarto user or you're curious about the new fancy Quarto ecosystem. If you're using Quarto, then you automatically have point two, that is, you're able to create a bunch of different types of documents. And you also haven't ventured into styling yet, because this is a talk about how to style. So imagine you're doing a weekly report at work and some of the higher-ups want you to use the corporate theme.

This might not resonate with you, so we can pop out some of these things. So instead of weekly reports, it should be, write a slideshow for positive times. Higher-ups should be yourself. And corporate design should be water-tolerant CETL theme. But really, as long as you can mix and match until it aligns with what is happening in your life.

So what I see, and I felt this too, is styling is incredibly daunting because there's so much happening and there's so many people that are so much greater at it than I will ever be. And you think, this is taking forever, and it could take forever. And what I'm hoping that you will take away from this talk is that it doesn't have to be. I have the opposite problem right now, is that I just spent too much time writing slides. But the same principles still hold, that to create beautiful products, you don't need a lot. You can get very far with just a little bit.

You can get very far with just a little bit.

And personal advice, I time-block myself with styling, so whenever I do slides, I set aside time first to figure out the theme, and then once that's done, I write content and then I never touch the theme, unless there's a little critical error. So with little effort, we can do quite a lot. And in this talk, I'll talk about the main three things. So I'll talk about how just by changing the color, font, and size of the different elements in your total output, you can do quite a lot.

Writing a theme for HTML documents

So how do you write a theme? We've already seen a couple of people have talked about this so far. And it will depend on the format you're using. So if you have some HTML document or website, you need to use CSS, maybe some JavaScript if you're fancy. PowerPoint has a whole different way of setting things up. LaTeX also has a whole different way of setting things up. So every type of input is slightly different, but the general idea is the same. And the total website has the documentation of where to find everything. For the rest of the talk, I will assume you know what you want. So I won't be talking about how to find the perfect font and perfect color palette and how to do all of that because we simply don't have the time.

So here is a very simple, well, this is the default HTML page for Quarto that comes up when you just start a studio, add new thing. So here on the left-hand side, we just have it. And it looks like how we expect. We have headers coming up. We have plain text. We have toad. It prints out as well. Main thing is we have a little format up here. And on the right-hand side, we see how it looks once it has been rendered.

To be able to employ theming for HTML, the only thing we have to do, well, there's two things. First, we need to tell the document, I want to use this style template. So we set theme and then specify in the theme. You can technically add multiple if you want. And since it's CSS, we have to test it in stylesheet so it will just know, put them all together and use whatever is most recent. Once we have that, we generate the corresponding CSS document. For Quarto to be able to use this properly, we need these comments to denote that this is a proper CSS file and different things should be placed roughly in these different places. But it shouldn't quite matter where you put it.

So the way I do it is I'm very opinionated in the way I create my stylesheets. And you will see that if you look on GitHub what I have. I always start by generating my color palette. And I always name it with $theme- and then the human readable name of the color. So here, I'm creating a black, a white, and a teal and a blue just because we need some colors. It doesn't have any deeper meaning about it. In general advice, when you're doing any kind of theming, whether it be for fun or for corporate use, you don't want too many. You can do a lot with one, two colors, maybe three. But once you start adding more, you get some dilution of it.

Another thing you might have noticed is I have my black and white that I'm using. But the black isn't the blackest black possible. I'm using a very gray but not all the way black. And that's simply because completely pitch black text on completely white background is very straining for the eyes. So just reducing a little bit of the contrast is pleasant without you really noticing that it's a thing. You still need a high enough contrast that you can actually see what's happening. But generally, going a little bit down. And the reverse is true as well. So you don't want white, white text on a dark background. Try to pinch a little bit to there.

And with the colors, they should be different. There's a million tools online of how to find contrast, colorblind friendliness. So once we have these defined, I have four or five up here at the top, then we can use those variables and specify these SAS variables. So we see here we have body slash background. Quarto will see that and turn the right element on the document into that color. And there's a bunch of built-in SAS variables. They're all in the footer link. So we just specify those down and we're using the theme we see at the top.

Sometimes there's some styling that can't be accomplished simply by using the SAS variables. That's why we use the rule. So this is just plain CSS. But it's the SCSS variant, so we are allowed to do a little bit of math and manipulations. So you will see in my H1 header, which is the main header in the document, I'm using this dot and function right here. So I'm saying take this color and make it 50% darker. So we don't have a million head totes everywhere that might be slightly related. There's multiple colors in our document, but we only have two base colors. And you can get quite far with this, and it's generally a good idea if you can, maybe you can use this darkening and lightening thing. So have some coherent theme to it.

Changing the font is just the same. Since we're working with HTML, we can use some Google font setup to pull in the fonts we like. And then we have SCSS variables, just the same, to set the variables, to specify things, and Quarto will just know what to do, make everything happen. And lastly, sizing.

I'm a broken record by now. You set them up as SCSS variables. There is this great idea of the font size of the root. So this is just the size of the main text of the document. You set that. But then, most every styling of the rest of the document is computed as a function of this root. So the h1 header normally defaults to two and a half times the root. h2 is two times, and so on, and so on.

Here, we could have stopped by just changing the root size, but I decided to show, as well, we can also use our variables, then, with a little bit of math to create a more coherent theme. And because there isn't a SCSS variable to control the way, the sizing of the tote, you can also manually find those and create them. A general tip I would use is look at what other people are doing, because someone has probably run into this before, and you should steal that an artist to figure out, oh, they're doing something neat. Let me take that.

And so we have a document right here, and it looks really nice. And to really bring up how nice it looks, I want to show the original we worked with. So by just doing a couple of very small modifications, we are seeing that our document have a whole new life. And I would argue that all the transformations we can do here can be done by yourself in an hour, maybe even less. Once you get used to it, it takes 10 minutes, because you just take the file, change the values, and you're done.

Creating a Quarto template

So we did it. We made a theme, and we're happy, and we realize, oh, this isn't just a one-time thing. I want to be able to use this theme over and over again. I want other people to use it over and over again. What do I do? So this is where we bring in the idea of a total template.

So there's this great tweet by David Robinson, and I'll read it for you right now. It says, when you've written the same code three times, write a function. When you've given the same in-person advice three times, write a blog post. And I would take the honor of extending this. So when you're needing the same styling three times, write a total template. And I'll argue it takes less time to do the total template than it is to write an R function or to write a blog post.

So when you're needing the same styling three times, write a total template. And I'll argue it takes less time to do the total template than it is to write an R function or to write a blog post.

So creating a template. We start by creating a data repository. It isn't technically necessary, but we start by creating a project right here. This is what it would look like. We have our index.tomd, which is what I normally use as my base name, and we have our styles, and we have a bunch of other things that happen when we create a studio project.

The first thing we do is we rename the main document we're working with to template.tomd. That lets Quarto know that this is the file that is the base of the template. That's the one that needs to be copied over. And we're done. We made a template. Now, if this is on GitHub, you can use the terminal command, quarter use template, the name of the GitHub repository, and this file structure will be copied over to wherever loader you point it to. And the template is what's being used.

It will ignore hidden files by default. So it won't copy over the R history, the dig files, or all the things you normally don't want to be copied over anyway. And if there's other things you don't want, like the RStudio project file, we can use this .totalignore file added in here to then specify where it's to say, oh, don't use this, don't move this file over as well.

I said that we don't technically need a GitHub repository. Instead of GitHub organization extension, you can point it to, like, a zipped file. So if it's a Quarto environment, you might not want to put the theme publicly for everyone to see. As long as the user is able to point to the zip of this file, it should all, like, to a zip of the folder, everything should work out well. You can also, I showed a very simple here, but you can use, put other things in it. Here, the template is just whatever document you have. You could put boilerplate in there as well. So you can really put whatever is in, like, the useTemplate function is, in a way, just a copy-paste. But it allows you to reuse the same things over and over again.

All right, that is all I have. I hope you create pretty things before I let you all go. I want to point you towards the Twitter documentation. So twitter.org, it's great. If you go on GitHub, there's already, like, dozens and dozens of templates for you to use. And on my personal blog, on the third link, I created this thing called Slidecraft 101, where I try to tell you how to make fun things with slides. And I've done three in a year, so it's going slow. Thank you.

Q&A

We have a couple of questions, and we have time, too. So first one, what advice would you have for those of us that are perfectionists and that need to let go and spend less time styling, but you just struggle doing so? Oh, so brilliant question. So by default, you're never done styling. Like, there's always more to do. So I would suggest, like, the time blocking, to do the high-priority items first, and then say, I have two hours, or I have four hours. I time block myself to one days of work. So I say, like, on the 25th, I style, and then I won't style anymore. And then I might be sad because I couldn't do anything, everything I needed, but that's how you have to do it.

You kind of answered the second question, which is, what's your self-imposed time limit for creating a theme? Yes, so slide themes, one day.

OK, how do you check the accessibility of your colour choices as your design gets more complex? Yes, that's a great question. So for, like, for colour themes, there is all these great websites of how to do colour contrast. There's a link on the first blog post in the Slidecraft 101 series of how to do this. Yeah, like, contrast and colour, they have some apps, I don't remember the name, but it's a macOS app that will turn your whole screen into a colour blindness simulator. So you don't even need to do anything. It just makes your whole computer look like different colour deficiencies.

Important question. What should you prioritise in styling? Well, above all, we are creating products for other people to see. So the most important thing is that the person on the other side is able to understand what is happening and extract information. So clarity above all, and then fun last.

So are there any helper packages or other tools for this, like what Scheringen Themer was, to help you with the styling or your choices? As far as I know, no. But I feel like the SAS variables is basically like how to make a theme because you set four values and it looks great if you pick great values. So I feel like you don't really need more theming because the SAS variables capture 90% of what you need.

So let's thank Emil again and also thank all speakers of this session.

Styling and Templating Quarto Documents - posit::conf(2023)

Transcript#

Writing a theme for HTML documents

Creating a Quarto template

Q&A

Featured software#

Quarto