Quarto Websites 1: Build your homepage | Charlotte Wickham & Emil Hvitfeldt | Posit
In this video, you’ll get a running start by using a template we've designed to be functional and attractive, and that will serve as a foundation for the rest of the video series. You’ll customize the content of your homepage, and how it looks, and along the way learn about the two key files in a Quarto website index.qmd and _quarto.yml. Finally, you’ll learn one way to publish your website so other people can see it. In this video: 0:21 Use a template to get started 2:33 Preview the template homepage, index.qmd 4:12 Customize the content of your homepage 5:45 “About” pages 7:22 Customize the image on your homepage 9:24 Website configuration, _quarto.yml 10:40 Customize colors with YAML 13:45 Customize fonts with YAML 17:00 Publish your site Links: About pages: https://quarto.org/docs/websites/website-about.html Appearance options you can set in YAML: https://quarto.org/docs/output-formats/html-themes.html#basic-options Code: Starter source code: https://github.com/EmilHvitfeldt/website-template Final source code: https://github.com/cwickham/quarto-website-video/tree/v0.1 For more in-depth coverage and slides check out: https://posit-conf-2024.github.io/quarto-websites/ Do you need a professional website to showcase your work? If you’ve used Quarto to produce a document, you’ve already got the technical skills to create a Quarto website. In this video series, you’ll learn everything else you need to build a website and customize its appearance. This video series is for you if you: - Have used Quarto to generate documents (e.g. HTML, PDF, MS Word etc.) - Are comfortable editing plain text documents (e.g .qmd) in your IDE (e.g. RStudio, Visual Studio Code etc.) - Want to walk away with your own personal website Taught by: Charlotte Wickham (https://www.cwick.co.nz/) Emil Hvitfeldt (https://emilhvitfeldt.com/) Videos in this series: 1. Build your homepage [https://youtu.be/l7r24gTEkEY] 2. Add pages and navigation [https://youtu.be/k65E-8PXZmA] 3: Customize appearance with CSS/SCSS [https://youtu.be/pAN2Hiq0XGs] 4: Add lists of content with listings [https://youtu.be/bv_Cw-3HI1Y]
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
In this video, we'll start from scratch and you'll get a template that we're going to use throughout the video series to build up your website. But the real focus of this video is your homepage. So by the end of it, you'll have a homepage, it'll be customized to you, and we'll even have customized some parts of that appearance.
Getting the template
So to get started, we're going to use a Quarto command to get a template. So I'm over here now in RStudio. I don't have a project open, but I'm in the terminal pane. And on the terminal pane, I'm going to use Quarto.
And this function is called useTemplate. And what you give useTemplate is a GitHub repository. And this command is just going to grab the contents of that repository and bring it down to your computer. So we're going to use a template that we've prepared for this series. And I am going to use my nervous bell, Emile's GitHub username, right? So I'm actually going to copy and paste that in.
So this is of the form sort of repo owner, Emil Hvitfeldt, and then the repo name, so website template. And I'm going to hit return and Quarto is going to run off and get that for me. It's going to ask a few questions. So do we trust the authors? Yes. Do I want to You can see I'm currently on the desktop. I do want to put my website in its own directory. So I'm going to create a subdirectory and I'm going to call it website. So Quarto goes off and it pulls down all the files in that template and brings them down locally.
And you can see I've now got this website folder sitting on my desktop. And I'm in RStudio. I'm going to actually open that as a new project. So in RStudio, I'm going to file, open project, and I'm finding that website folder on my desktop and opening that up.
If you're in something like VS Code or Positron, you might want to open up that workspace. And you can see our file browser is also in the right place. So these are all the files that are brought down. And a lot of these files are going to be things that we're going to talk about and build on in later sessions. Today we're really just going to focus on two files, index.qmd and underscore quarto.yaml.
Previewing the template homepage
So I'm going to open up index.qmd. So like any Quarto document, this file has some components in it. And the first one being a yaml header. So we've got the three dashes indicating the start of the header. And then all the options are inside that, ending with another three dashes. Then everything else in this file is the content. And that's in markdown, like any other Quarto file.
And it could have code cells in it, just like any other Quarto file. The first thing I'm going to do is I'm actually going to preview this. So in RStudio, that's the render button. If you're in VS Code or Positron, it's called preview. Basically does the same thing. That's going to run it through Quarto and pop up a preview of this file. And because this is a website project, and we'll talk more about how Quarto knows it's a website project later, it's going to look like a website when you preview it.
I've got everything zoomed in here, so we're sort of actually seeing what this would look like more on a mobile device. So sometimes you want to pop that out into something like, you know, into your web browser to see what that would look like more generally. And that's one of the really nice features of Quarto websites, is that they have this property that they scale down to mobile size really nicely. This is our template website, and you can see it's built for this fictitious person called Alicia.
And that's one of the really nice features of Quarto websites, is that they have this property that they scale down to mobile size really nicely.
Customizing the homepage content
So I'm going back to RStudio. I'm now in this, still in this index.qmd file. So the first place we'll start is in that YAML section, and you can see that some of these YAML items are translating directly into content on this page. So we've got a title that says Alicia, that's that big name, and the subtitle is sort of coming on underneath. If this was me, maybe this wouldn't be Alicia, it would be Charlotte, maybe I'd like my last name, maybe I would change that I'm also an educator as well as a data scientist.
And if we make those changes, we save that file, we can rerun the preview. I tend to use the keyboard shortcut for that, I'll run that now, and you can see that those changes are happening right on that home page. So some of the things here are controlled in this YAML. We've got the title and subtitle. You might guess that this image is controlled by that image key, and it is.
But the rest of the content on this page is actually coming from the content part of our document. So the template has it set up with a couple of headings like education and experience. It's entirely up to you what you put there, right? You might have a little paragraph just describing who you are. A really sort of lazy way I like to do this is just to put in some placeholder text, knowing that I'll come back in later. Here I'm using the shortcode ellipsum, and it just adds in sort of a paragraph of text.
About pages
So this particular page is actually a special kind of page in a Quarto website called an about page. And what an about page does is it uses a template to combine things that are defined in YAML with the content of the page.
So we've got sort of these title and subtitle, that's coming from YAML, and then everything that's the content you can kind of see here. And then way down at the bottom you'll actually see there's also a couple of links to GitHub and LinkedIn. And those again are coming from the YAML.
So let me show you that. So the way you make an about page in a Quarto website is you use this about key in your YAML. And these about pages, like I said, are based on a template. The template we're using here is called Holla. There are a few of these. Let me just show you another one called Trestles, just so you can see what kind of changes those templates make. Right, so the difference here is now the image is on the left along with the title and subtitle and links, and all the content is kind of on the right, this little bar on the dividing them. So you can head to the docs. There's a link right there in the YAML to see what other kind of templates you can pick.
And then those links are defined in this YAML too. So there's a link to GitHub. I might put my own GitHub in there. Maybe I don't want a LinkedIn link, so I can just delete that. And when I preview that, that sort of changes those links there.
Changing the profile image
So that gets you a long way to a really custom home page. The other thing I haven't shown you here is how to change this image. So that image you can see in the document YAML. I've got an image key and it says profile.jpg. That is coming, well that is referring to this file sitting at the top level in that directory. So the paths you provide to image should be relative to the location of the file that they're in. Index.qmd is sitting at that top level, so when I say profile.jpg, it's just looking at the top level for that image called profile.jpg.
I found an image earlier that I'm going to include here. So this is the image I found earlier. It's a nice picture of some trees. What do I do if I want to use that instead of the template one? The easiest thing is probably just to rename that. So this came from Unsplash, so thank you to dglix-ganzorig for that image, but I'm going to just change it so it's got the same name as what the template is currently expecting, profile.jpg, and I'm just going to drag it into my website folder and say yes, I do want to replace what's there.
Right, so I'm literally just replacing this image file with something different. So I'm going to preview it and then it should pop up with that new image. And you can see there it is there. I actually think now my image is taking up a bit too much room. There's this cool option in the about key that controls the image shape. So I'm going to look for image shape and I'm going to switch to round. I think that just makes it a little bit smaller. You can see on a bigger screen it just fits a little bit better.
A homepage is as easy as that in Quarto. You can use this template, you can edit the yaml to change a lot of the things on the page, and then the actual sort of content becomes integrated in that about template and also shows up on the page.
The _quarto.yml configuration file
There are some things on this page, let me go to the Safari view, that aren't controlled in that file. Right, you'll notice that there's sort of a navigation bar at top, it's got perhaps some redundant links to home, and there's a search up there, and then there's a footer at the bottom of the page too. So some things in your website are controlled not in a Quarto file but in this underscore Quarto dot yaml configuration file.
So I've opened it up and it's this file here under the project key and then type where it says website. This is how Quarto knows that this folder, this directory called website, should be treated like a website. Then there's a key called website and this controls a lot of the parts of that website, the nav bar, the title of your website, where the social is turned on, what the footer looks like, these are the other components that you see on that page, this is where they're controlled. And then the final thing in here under format html, these are the html document settings that are going to apply to every page in your website. So this is where you can control the appearance of those pages.
And that's something that I'm going to hand you over to Emil to tell you more about.
Customizing colors
So in this first round where we are changing the colors using the yaml file we've been using so far, there's a couple of different options we can set that changes the way the website looks. And those attributes are font color, link color, background color, and monobackground color. And they're fairly self-explanatory. The font color is the color of all the text on the website.
Link color is the special color of whenever we have a link going out. So if you have a link, all the buttons have to use this color as well. Background color as we expect. And the monobackground color isn't something we're using right now. But if you're using any code chunks using Python or JavaScript, it will use this monobackground color.
So to see how we can use it, we're moving back into our website we've been using so far. And we move over to the total yaml. And inside down here in format.html, we can go and say start by choosing the background color. If we type slow enough, we get this auto-complete hint. Let's see if we can get a background color that's a light green happening. A nice little light green. We can make it maybe ee ff ee.
So now we have to complement the greenery in our image. We can use some greens that match. To do font color to also show, we can also pick some of these built-in color names that are accepted with CSS. So here we can use a dark green that we can see is being used here in the plain text. And lastly, we have this very neon green green link color right here in the GitHub button. So let's see if we can fix that. And let's maybe go back and make it all the way black too. So now when we hover over this button, it turns all the way black. That's the way the link works.
We don't have any real links in the website right now, but that will be controlled using this link color option. We can also see that there's many different ways of selecting a color. I've showed both using these RGB hexadecimal values, which you can easily find color pages for online or downloaded apps. There's also a long list of name colors, but there are many, many other ways we can select color for our website. And these are nothing special. They're all the standard CSS ways of selecting color. So knowing these is very useful as a general tool.
Customizing fonts and sizes
The fonts we can select come in two different ways. Right now, we have the main font, and then the font that's used everywhere on the website, and the monofont, which is used for code, which we don't really have right now. We select these in slightly different ways. We'll explain it real fast.
So it's typically called a font family, so it is a name denoting what font should be used. And you might have seen whenever a font family is selected, it has this comma-separated approach. We're doing this comma-separated approach because it allows for the idea of fallbacks. So if the first selected value isn't available, it will set the next one, and so on and so forth. This allows for mistakes or slow internet. If it can't download the most preferred font right away, it will fall back to a font such as the sensor, which is available on all machines.
So the way we find that is we go back to our website, and we say main font. And now we need to find an option. What happens if we just pick serif, and we see right away that the font updates. So now we'll use a serif font. We can also, I want to say monospace. So selecting a monospace font isn't really the most appropriate font for body text, but we can see here it's being selected out and being used all across. In some of the later videos, we will show how to use any font you want. Right now, we're limited to some of these more system-level fonts.
And the last thing we can do is change the sizes. And the main three sizes we can change right now is the max width, which is the width of the text area of the page, the font size, which is the size of the font, and the line stretch, so the distance between the lines of text on a page. All of these sizes can be specified in a million ways because it is CSS, but common sizing includes the pixel sizing. So we can say 18 pixels high or 100 pixels wide would be too much.
So we can go back in here. We can say font size. And so let's try to go all the way up to 20 pixels. And now if we pull it out here, we see that it got better. So finding the right size is, there's no right way and no wrong way. Of course, it needs to be not too big and not too small. Anywhere around 15 to 20 is a reasonable default, but it will depend on the font you choose. So if you choose a different font, it might just naturally be smaller than other fonts, and you would have to adjust the font sizing accordingly.
Publishing the website
So now that we created our first slightly custom website, it would be fun to be able to show it to someone else. There's many ways of doing it, but one of the ways I really enjoy it is with this thing called quarto-publish. So it's a terminal command, and we simply type quarto-publish. That will publish it out to a number of different places, but we can specify specifically some different locations. So we can also do Netlify and other hosting sites, but we have this quartopub place where you can create an account and publish your Quarto stuff.
So we run quarto-publish quartopub. Let's say yes to my email. Let's give it a name, so I can call it home. That's fine. Wait a little bit. It will render locally the website before it pulls it up, and then it starts uploading. It will wait a second, and now we have the website we just created on this website that's now available for everybody to see.
So that is one very quick way of getting your website out into the world.
