Quarto Websites 4: Add lists of content with listings | Charlotte Wickham | Posit
Adding a listing page to your website is a great way to showcase your projects, talks, publications or blog posts. In this video you’ll learn how to create a listing page in Quarto and see two ways to populate it with content: Quarto documents, or a yaml file. In this video: 0:50 Use a listing to add a blog 3:36 Listing options 5:47 Why use a listing? 7:22 Use a YAML file to populate a project portfolio 9:50 Customize the display of a listing 12:10 Advanced customization of listings 13:42 Remove pages Links: Listings: https://quarto.org/docs/websites/website-listings.html Andrew Heiss’ teaching listing: https://www.andrewheiss.com/teaching/ Code: Starter source code: https://github.com/cwickham/quarto-website-video/tree/v0.3 Final source code: https://github.com/cwickham/quarto-website-video/tree/v0.4 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 the last video you saw Emil make some tweaks to the styling of this website. Now we're going to kind of go back to what we were talking about prior to that, navigation. And I'm going to show you a different way to add navigation to a Quarto website, and that's this thing called a listing. So a really common use of a listing, and this is where you might have seen it used before, is in a blog. The page that makes that listing of all the blog posts that people sort of land on and then can browse through, that's an example of a listing.
So we're going to add one of those to this website, and then I'm going to talk about a few of the other features of listings that make it a really good candidate for adding other things to your website, like a list of projects, or a list of talks, or a list of publications. Okay, so I'm going to head back over to RStudio. Here's our website project as we left it. And one thing you'll notice is there's actually already some files in here that might be appropriate for a blog. So over in the website directory there's a blog directory, and there's three other directories, and inside each of one of those is a Quarto document that's like an example blog post. So we're going to try and build one of these landing pages for the blog that gives us links to all these posts.
Creating a blog listing page
So how are we going to do that? The first thing we're going to do is create a new page. This is going to be the blog landing page. So I'm going to create a new file. I want it to be a Quarto document, and I'm going to add the title here. It's just going to be blog. Now I'm going to save that. Where am I going to save it? I'm going to save it inside that blog directory, and I'm going to call it index.qmd. So remember that means that people will navigate to this page by going to our website, and then they'll say blog forward slash, and they should get to this page.
Okay, so I've saved it. I'm going to render that just so we can have a quick look. Right there is a blog page now that exists on my website. It's got nothing on it. The first thing I'm going to do though, before I put any content here, so I'm going to go back to underscore dot yaml where you know that we can add items to our navigation, and over in my nav bar, after my link to talks, I'm going to add a link to the blog directory index.qmd. I'm going to save that, and we should now see that in our navigation we have that link to the blog page.
So we've got this blog page as part of our site. People can find it. There's just nothing on it. So let me show you how easy it is to add one of these listings to a Quarto web page. It's as simple as adding another item to the document. Yaml, listing, and I'm going to say default. Basically I'm going to provide no options to that listing, and I'm going to regenerate the page, and almost by magic, I'm actually going to go over to Safari so you can see this, like almost by magic we now have a blog.
So the listing here, I've just used all the default settings. What that means is Quarto is going to look in the directory that this particular page is in. So it's inside the blog directory. It's going to look for any other Quarto documents in there, and it's going to create a list of all those documents automatically. So it's looking inside those documents for their titles and their descriptions, and it's generating this list of blog posts. So that's what a listing is. It's a list of other content, and you can see you get this kind of nice default automatic styling.
So that's what a listing is. It's a list of other content, and you can see you get this kind of nice default automatic styling.
Listing options
Okay, so what I want to show you a couple of the options you have when you create a listing. So I'm going to now sort of deviate from the defaults. So I'm going to add some sub options to the listings option here, and the first one I want to show you is one called contents, and this is where Quarto should look for the things that go in this listing. And when I did that default setting, it was sort of equivalent to saying, hey look in this directory, and you can say that with just a slash. If this file, this blog landing page, had existed sort of one level up at the top level of my directory, I would have been able to say, hey look in the blog directory for this content.
The other really important argument to listings is the type of listing you want, and the type we're looking at here is just the default type. There's another one called grid, so let me switch to the grid type, regenerate it, and then I'll show you that over in Safari. It sort of gives you more like these little rectangular tiles that get laid out in a grid. So that's another variation, and then there's another built-in type called table, and that sort of literally gives you a table of this content. So they're the three built-in types that give you quite a lot of flexibility.
Why use a listing?
So to sort of sum up what a listing is, a listing is an automatically generated list of content. You didn't have to do any work to create that list, you just had to tell Quarto where to look for this content. It's styled via a template, so we saw that you could say type just default, and you get kind of like a blog style listing. Type grid gives you this grid layout, and then type table is very literally a table of all these links. And a listing in Quarto can be included on any page, so you just create the page and then add that listing item to the YAML, and you get a listing.
And the way that Quarto does this, the way that it's generating the links on that listing page, is it actually goes in and looks at those files and looks at the front matter of them. So in those files, in that blog directory, those Quarto files have things like the title set, the description set, the author set, an image set in that YAML, so that Quarto can generate that nice little link to the content.
And you might be asking why would you want to use a listing? Listings are really great when you've got a very large collection of content, so you don't want to sort of by hand create links to all these things. They're also really good for things that grow, collections or lists that grow. So if you've got something like a list of projects that you're adding to over time, a listing makes a lot of sense because you can set it up once, and then it's just a matter of adding in the content when you want to expand that list.
So what you've seen is a listing is something that's really common with blogs. You'll see them out there a lot where people list, it's like a list of blog posts. But listings can be really useful for other kinds of lists. So I'm going to show you a few examples. Here's an example on Isabella Velasquez's homepage where she's using a listing to list out her projects, so sort of like a project portfolio. Here's another example, this is from Megan Hall, and this is a listing of talks. So rather than sort of creating the talks list by hand, each one of these is a piece of content that has a little bit more details if you click on it, but the listing is being used to lay out that list of talks. And then here's another one from Mikhail Kanui, which is a listing of publication. So if you're in the academic sector, this is something you often need to have. And each one of these listings is actually a link to a published paper on a publisher's website.
Using a YAML file to populate a listing
There's lots of different uses for listings that go beyond blogs. One of the things that's really useful with listings is that you don't have to provide individual pages of content to create a listing. So let me show you another way you can do listings. I'm going to go back to the RStudio project, and there's another example of a listing that's already in this template, and it's under this projects folder. I'm going to have a look at index.qmd, and the first thing I'm going to do is I'm just going to render this, just so you can see it. So this file, this page, has been there the whole time. We've just never had it in our navigation, so you probably haven't seen it.
Let me pop that open a bit bigger. So this is an example of like a project portfolio type page, right? I've got this page called projects, and then there's currently just three things on it. They've got a title, and a little bit of a description, and some categories that go along with them. Now the interesting thing about this particular example is that if you look at the way the listing is set up, the contents isn't a folder in the website project. It's actually pointing at a file, a yaml file, and if we go and have a look at that file, so projects.yaml, inside the projects directory, this is a file that's written in that yaml syntax. That's the same syntax you use to set options in Quarto underscore Quarto dot yaml, or in your document header. But what I'm using it for here is to provide a list of items that I want to have in my listing.
So each of these items, you can tell there's an item because it starts with a dash, I've got three of them here, those three dashes. Each one has a title, a path, that's the element you use to provide a url. So since this isn't a page of content, when people click on this item, they're not going to go to a page within my website, they're going to go off to some external url. So it could be that some of your projects actually, like the best place for people to look at is to go look at github, right? This might be a link to a github repo. It might be other projects, you know, it's just a slide deck, so you want to point them to where that slide deck is published. So using these yaml files for listings is a great way to list things where you don't actually have a page of content on your website that describes them, you just want to have a title, description, and then send people somewhere else. The image is what's being used in those thumbnails, in the description, etc. There's categories and date as well.
Customizing the display of a listing
So again, that's sort of what a listing looks like when you generate it from one of these yaml files, and here I was using that grid type. I'm going to switch that to table because I do want to just show you a couple of quick, easy customizations you can do with listings. So let me re-render that. Now I've got these projects in a table, and the first thing you might notice, if you've only got three projects, people really aren't going to need to reorder them or filter them. So I'm going to get rid of them.
Those come, you can control them with a couple of yaml keys. There's the sort UI. I want to turn that off, so that's going to get rid of the order by box, and there's a filter UI which I'm also going to turn off. Okay, so just re-rendering just to show you I've got rid of those. The other thing that I think, when you have a table, like these little images don't really add much, so you might want to get rid of them. Or you might have additional things you've specified in that yaml that you want to include that wouldn't be included by default. So I'm going to add this yaml. This yaml option is called fields. What do you want to show up in the listing as the columns in this table case? So what fields do I want? I want title, and I want the description, and I want categories.
I don't think I want the date, right? Projects aren't really often associated with a specific date, so I'm not going to put that. But if I specify now just those three fields, those are the only ones that show up in this table. And then the other thing you can do here is there's an option called field display names, which lets you change the names that are being shown in those columns. So I might change title to project. This is sort of more of a project portfolio. And instead of saying categories, if I'm really using this to kind of show people what I can do, I might change categories to skills. So let's make that change, and then I'll bring that up a bit bigger again, right? Now this feels more like a project portfolio, because I've got what's the project name, what did I do, and what were the skills I demonstrated in doing it. So that's a really simple kind of way you can customize these listings. Use that type table, and then you can play with what shows up in the columns, and what the column names are.
Advanced customization of listings
But listings are incredibly customizable. So the first thing I want to do is show you an example of someone using listings, which really demonstrates the breadth of things you can do. So here's an example of someone using a listing. This is Andrew Heiss's teaching web page, and I want to show you some of the things that go beyond what I've shown you so far with listings. So the first thing is that you can have more than one listing on a page. So in this case, Andrew's using a listing for each academic year. So there's a listing that's generating these first two items, and there's a separate listing that's generating these next three. So the first thing to know is you can have more than one listing on a page.
And along with that, you can put a listing wherever you want on the page. So if you want some content first, and then to have the listing, you can do that. And the way Andrew's using that here is just to say, in his source, he's got like, here is where the listing goes for this year. Here is where the listing goes for last year. And then the other thing that's going on here is he is not using that type table grid or default like we've seen so far. He has built a completely custom template for how each of the items appears. So in his custom template, there's a place to put the sort of hex sticker. He's controlling the way that the title appears, that there's in this case like a course number and where it was taught, and then these really nice little orange links. These are kind of a custom part of his template. Sometimes there's only one, sometimes there's a couple. So listings are really powerful in the way that you can customize them as well.
So listings are really powerful in the way that you can customize them as well.
Removing pages
Okay, so that's listings. This really powerful way to add pages where you're just listing other content in a Quarto website. So one thing I wanted to mention as we wrap up is that if you've got your page now built out, but you're like, I don't need a blog, I don't need this project listing, just remember that removing a page from a website is just like adding it. You want to get rid of the file that's generating the content, and then you want to make sure it doesn't exist in your nav. So you've sort of seen how we could have this blog. If you don't want that blog, you want to delete the blog folder, and then you want to make sure you delete any navigation you might have added as you're playing around from underscore Quarto.yml. So that's the end of this video. You've learned about listings, this powerful way to add lists of content to a Quarto website.
