Quarto Websites 2: Add pages and navigation | Charlotte Wickham

Transcript#

This transcript was generated automatically and may contain errors.

In the last video we started with a template and then we edited index.qmd to make our home page so that it reflected us and then we edited underscore quarto .yaml to change a few of the styling things, a few of the fonts, a few of the colors and then finally we published that website so it was available for other people to look at. In this video we're going to talk about how to add things to that webpage, how do you add new pages and in particular how do you make sure people can find those new pages through your website's navigation.

Okay I'm going to come back over to RStudio and pick up where we left off. So I've got index.qmd open and I've previewed that and it's showing over in the viewer and in RStudio sometimes because it's small you see a mobile view so I'm also going to pop that out and have a look in the web browser. So there's our website, it's got a photo, some details about us and we've made a few edits to the color we've added this green and some other fonts.

Adding a page to your website

Now we want to add a page. So to add a page you have to make two decisions. First of all you have to decide where the source of that page is going to live in your project. I call that the structure and then you need to figure out how when people come to your home page they're going to discover that other page and that's the navigation. Okay let's start with the structure. I'm going to go back to RStudio and I'm going to create a new page.

When I want to create a new Quarto document I tend to just create a new R script through the new R script shortcut and then switch it from R script to Quarto. Let me just minimize this to get it out of the way. Okay so this is going to be a Quarto document. It needs that YAML header at the top. I've got my three dashes and closing three dashes and this page I'm going to add, I want to use it to document all the talks I've given. So I'm going to call it talks for its title and then there's going to be some content here. If this was for real I'd be fleshing it out with all the talks I've given. I'm going to use that Lipsum shortcode again just to give it some placeholder content.

Okay so that's a really simple file. This is going to make a really simple page on my website. The first thing I have to do is figure out where to put it. So I'm going to save. I'm just hitting the command s or control s shortcut to save the file. So here I am, it's sort of by default in this website directory. You have to save all the files you want on your website inside your website project. But where do I put it? Well I'm going to make a pretty simple decision. I'm going to call it talks and I'm just going to stick it at this top level in this website directory. So let me save that and just to kind of confirm that like I'm over in my files pane in the website directory and there is that talks.qmd file.

Okay let's preview that and I'm going to switch over to the browser again. So there it is. There's my brand new talks page. It's got some content on it.

File structure determines URL structure

The first thing I want you to notice is the URL. The URL starts with this localhost 5078. That's just like the web address for this local preview. When you publish this that's going to be replaced by the actual URL for your website. And then you can see forward slash talks.html. So the URL for this new page is going to be your website address and then forward slash talks.html.

And in general the structure of your website, the files and folders that you make in your website project, are going to determine the URLs that people see on your website. So we just saw this example. If you put a file like talks.qmd at the top level of your website project, it's going to end up at the top level of your website at talks.html. If you put it inside another folder, so if I made a folder called reports and I put an airquality.qmd in there, then that file, when it's a web page, is going to live at your website address forward slash reports forward slash airquality.html. So the structure that you put into your website project is going to be reflected in the structure of your website once it's published.

So the structure that you put into your website project is going to be reflected in the structure of your website once it's published.

So index is a little bit special. Index.html is kind of like the default page that people hit when they go to your website or to a folder in your website. So we've seen this already, right? We edited index.qmd. That gets rendered to something called index.html and it's what people see when they land on your website. They put nothing else in the url. This also works if you create subfolders. So if you created a folder called talks and you put a file inside called index.qmd, people would get to it by going to your website and then saying forward slash talks. Like no .html, nothing else on the end, they just say forward slash talks. They'd get to that page index.html created by the file index.qmd which is sitting inside the talks folder.

You're not limited to just using qmds to build your website. You can use plain markdown files, you could use python notebooks.ipynbs, anything called index.qmd or .md or .ipynb, that's going to render to index.html. And you aren't limited to html files either. So if you put something in your website project that was a csv file, maybe it lived in the data directory, that would be available to people that come to your website by going to your website url and then forward slash data and then forward slash the file name. You can do that with pdfs too. So if you had a pdf version of your cv, you can have that available. Or even if that pdf is actually generated by another Quarto file, that works too.

So back in RStudio, we've got this talks.qmd file. We've just put it at the top level directory. It's going to be available to people if they go to our website and then talks.html. But if we're over on our website and where someone's come to our homepage, right, like there's no indication here that this talks page exists. So we've also got to figure out how we're going to add navigation to this page.

Let me go back to RStudio. We saw this briefly in the previous video, but navigation is controlled in this underscore Quarto dot yaml. And in particular, it's controlled under this website key. Under this website key, there's some general website level settings, one of which we've got right now is called navbar. And that's the option that controls this top navigation bar that's right along the top. And you can see underneath it, it says right, and then there's an item with the text home and href index dot qmd. That is the navigation you see, I'll have to go to the web version to show you this. That is actually the navigation you see over here on the right. In the mobile version, because of the small screen, it's actually collapsed down into this item in that hamburger menu.

So navbar is this thing that controls the navigation bar, the top navigation bar. And if I want to add an item to it, it's as simple as adding an item here and saying, giving a path to the source document for this page. So I created a page called talks.qmd. It's just at the top level of my website project. So that's all I need to say here. Add a link in the navbar to talks.qmd. And we should see that now if we save that, and we reload our page in the mobile view, we should now see we've got two links buried in that hamburger menu. And over in our full page website, you can see now we've got two links up in that navbar. We can get to the talks page, and we can get back to the home page. So sort of as simple as that, adding a navigation item is just a matter of adding an item, which is the path to that file in this navbar option.

Okay, what I did there was a little bit different to that link you see above it, right? I just gave it talks.qmd, but you can see in the previous example, there's a text item and an href item. So that's a sort of more comprehensive navigation item type syntax, and we could do that here too, right? Like I might say this is where I want it to point to, so that's the href, but maybe I want it to actually say speaking, something like that, right? The reason that in the navigation bar it says talks right now is because that's being pulled from the title that's on that page, right? It's literally being pulled from the metadata value title in that page, but it doesn't have to be that. We could change it to speaking. Let me just save that, and we should see that that now changing it up there.

The other thing you can do in these navigation items is add icons. There's one called megaphone. These are bootstrap icons. There's a link you can go just to see all those. I'll add that, and then you see you get this little icon as well. So to add something to the navigation bar, it's as simple as just adding a path to the file for that page that generates that page, but you could also do a little bit more detail and make sure that you can control what text displays and if there's an icon.

So one thing you might notice is this is all buried under this thing called right, right? There's actually another thing called left, and you won't see that on the mobile view, but over in the web view that's just shifted all our items to the left, and you can even mix and match, right? So maybe I want home on the left, but I actually want my link to my talks over on the right, and if we go back, switch back, we can now see I've got home on the left, talks on the right, and then there's another thing you can also have which is called tools, and these are navigation items where you don't really want any text, you just want an icon.

So I might say I want to add, like this is commonly where people add like a link to their github. It might be, I'm just going to do github.com so I don't have to type too much, but it might actually be like the link to where this website source is hosted on github. If you do that, you get this little icon, and these tools stick around in the mobile view, which is quite nice. Over in the web view you can see that that's what's added, that little icon over there.

There are some other things in this navbar that you can edit. One of them is called title, so you can add a specific navbar title, and I tend to like to put, like if it's a personal website, I often would put my name there, and you can see that that's going to change what was just called home there, it's changed to Charlotte Wickham . Let me show you that in the big view, right? This now says Charlotte Wickham, and that's actually a link to the home, so it kind of makes this one a little bit redundant. I'm going to get rid of that entirely.

Come back over. Okay, so now I've got this link here will always take you to the home page, then I can have all my other kind of navigation over here on the right, I quite like that. I don't actually like calling it, I'm going to switch back to speaking, I mean to talks. I kind of like my navigation items to be very closely related to the titles on the pages.

Okay, so that's that top navigation bar. There's actually a different type of navigation built into Quarto called side navigation, so instead of being along the top, it comes down the side. And to switch to that, it's as simple as swapping out navbar for sidebar, and then the sidebar doesn't have this concept of left and right, everything's just in one menu, and it takes the option contents. So I'm going to switch to that, just show you what it looks like. You get a little bit of a different feeling, there's now this bar down the side where all my navigation is going to live. Search box looks a little bit different, but you can see I still have those tools, there's still an available option in sidebar navigation. All right, I kind of happen to like the top navbar, so I'm actually going to switch back to that, so we can pick up there next time.

That's the very basics of navigation, there's this navbar option under website in Quarto.yaml, where you can specify the layout of the links in that top level navbar, or you can switch to a sidebar and have all your links down on the side. I want to show you some other navigational options and elements, and to do that I'm actually going to go to the documentation for website navigation in Quarto website. So this is in the guide on quarto.org, that's a page all devoted to website navigation, and I'm showing you it for two purposes. One is like this is the place to go to learn about all these other options, but it's also a really nice illustration of a ton of other options.

So the first thing I want to do is talk about the website as a whole. This website is built with Quarto, and you can see that at the top it has that top level navigation bar. It is using that navbar option to do that. When you're in pages on this website there's also that sidebar navigation. Now one thing you might notice is if you're in say the guide section of the website, the sidebar navigation has one set of elements, but if you go somewhere else in the top navigation, like the reference section, it's a different set of sidebar elements. And that in the Quarto world is known as hybrid navigation. So the top level navigation and the navbar sort of moves you around different sections of the site, and then once you're in one of those sections you get your dedicated sidebar for that section. So if you want to learn about how to do that, it's just a matter of specifying both some navbar and sidebar entries and linking them up. You can learn all about that on this page under the hybrid navigation section.

The other things to notice here that we didn't talk about that are available, for instance in the navbar, are you can put a logo in the navbar. There's a logo item for doing that. You can have items in your navbar that have a drop down menu. So those are other things you can do with the navigation. The other thing you might notice is in the sidebar navigation here there's actually a bit of hierarchy, like a lot of these elements you can drop into and there's a lot more elements. So you can also introduce hierarchy in sidebar navigation as well.

Some other things I want to point out is at the top of the page this little navigational element here sort of tells you where you're at in this section. It's called breadcrumbs. That's something else that you actually get automatically if you've got a nested sidebar, but you can turn it off as well. The other thing to notice is up in the top level navbar there is the search. That's a great way to search the website. So this sort of comes for free with Quarto websites or you can you can turn it off if you don't need it. I use this a ton on this particular website, the Quarto docs, because it's really easy to search for things. So for instance I just told you those things are called breadcrumbs. You might search for that just in the search box to find exactly the section where you can learn about that on this page. That search of course searches across all the pages on this website.

The other thing you'll notice that is on a lot of the pages on this website is down on every page there's sort of these links to GitHub to edit this page or to report an issue. You can also have a link there just directly to the source for this page. Those are called GitHub links and you can read more about how to add them on this page as well. If I scroll all the way to the bottom of this page you'll find another couple of navigational elements. You can see right at the bottom there's these arrows. You can go back to websites or forward to creating a blog. When you're in a section of the sidebar you can add this. It's called page navigation and it lets you sort of people navigate quickly back one element in the section or forward one element in the section. And the other thing that's down here right at the bottom is the footer, the page footer. And on the Quarto website there's some links, a little bit of an acknowledgement, and some sort of icon links. You can control all of them through this idea of a page footer.

And then the final sort of navigational element I wanted to point out that you can put in Quarto websites is of course this in-page navigation. So this is just a sort of a table of contents for this particular page that lets people navigate around the page. And that is a feature you've probably seen it if you're used to me making standalone documents in Quarto. It's an option to the HTML format. It's called TOC. You can turn it on with TOC true.

Wrap up

Okay so to wrap up this video what we've talked about is how to add a page to a Quarto website and that's simply you add a Quarto document to your website project and the location where people will find that document, the URL, is based completely on the file and folder structure you use in your project. So we added a page at the top level, that means it's going to be available at the top level of the website. You just have to append the .html on the end. The other thing we talked about was navigation and you've seen that the way you control navigation in a Quarto website is inside the underscore Quarto.yaml file. There's things like navbar and sidebar where you can control and add items to your navigation. And I hope I sort of showed you by looking at the Quarto website itself that there are a ton of other kinds of navigation you can add to a Quarto website. You can read about them in the docs, they're pretty much all just a matter of editing that underscore Quarto.yaml file.

There is one other kind of navigation that we're going to talk about in the final video and that's this idea of listings. Listings are a way to generate a page that's just a list of content. So you can create a blog by creating a list of blog posts, you could create a project portfolio by creating a list of projects. So that's a really handy tool in websites specifically like personal websites where you just need to sort of list things. We'll talk about them in the final video, all about listings. In the next video you're going to dive a little bit more into the styling of a website, in particular how to style your website using CSS and SCSS. And if you haven't heard about them before, if you don't really know what they are, that's that's totally fine. That's where we're going to pick up in the next video.

Quarto Websites 2: Add pages and navigation | Charlotte Wickham | Posit

Transcript#

Adding a page to your website

File structure determines URL structure

Adding navigation to your page

Customizing navigation item text and icon

Controlling where items appear in the navigation bar

Switching to side navigation

Other types of navigation

Wrap up

Featured software#

Quarto

rstudio