Add a Page to the Website

Tip Learning Objectives

By the end of this module, you will be able to:

  • Create a new page for an existing Quarto website

Create a New Page

Once you have a working website, adding content is straightforward! On your local computer, work through the following steps.

1. Make a Quarto File

Each new page requires a new file. Go ahead and create a new Quarto file. When you save it, keep in mind that the repository-name-to-website-URL relationship will also affect the link to this specific page. Check out the example below for one way of visualizing this relationship.

github.com/owner/repository/folder/file.qmd       owner.github.io/repository/folder/file.html

If you do not use sub-folders, the same relationship would occur just without the “folder” part. The take-away of the above is essentially that you should save this Quarto file with a brief name that is descriptive of this page’s purpose in your website.

2. Update the Global YAML

For this new page to show up in your website, you need to edit your “_quarto.yml” file so that Quarto knows where your page should be linked (e.g., in the navbar, in a dropdown menu, etc.). To do this:

  1. Open your “_quarto.yml”
  2. Add the new Quarto file to the relevant place
    • If you’re unsure, just add it beneath the line that references “index.qmd”
WarningWatch Out for Indentation!!

While indentation does not affect R code, it absolutely affects YAML code! A common source of error for Quarto websites is improper indentation for a new YAML element so double check the indentation of your additions against comparable rows that you know already work.

3. Test it Locally

To make sure that your new page displays as you desire, run quarto preview and make sure your website looks how you want it to. If it doesn’t, edit the offending file(s), save those edits, and look at the preview again.

WarningRemember to End the Preview When Done!

The preview will keep going until you manually stop it so be sure to stop it when you’re ready to move on.

4. Render & Push

Once you’re happy with how the preview looks:

  1. Run quarto render
  2. Commit & push/sync all changed files related to the new page
  3. Wait for the GHA to complete
    • The process for the GitHub Action is the same as it was when you first deployed your site so you can either watch the symbol on the repository landing page or get more granular information in the “Actions” tab of the GitHub repository
WarningSite Not Updating? Refresh the Page!

If your site is not updating but you’ve followed the above steps (and the GitHub Action is finished), you might try closing the page and re-opening it or refreshing the page. Sometimes it takes a moment for updates to the site to be visible if you opened the page before the GitHub Action is complete or as it completes and refreshing the page can fix it in this case.

Activity - Try it Out

NoteYour Turn!

Let’s take a break while each of you adds a new page to your website!