QUARTO FOR DOCUMENTING OHI METHODS

An intro to building, deploying, and customizing Quarto websites

Author

Sam Csik

Published

May 17, 2024


This document is based on teaching material originally developed for the Bren School of Environmental Science & Management’s Master of Environmental Data Science (MEDS) program. Check out Creating your personal website using Quarto, Customizing Quarto websites, and Adding a blog to your existing Quarto website for additional information and examples.

What is Quarto?

Quarto is a publishing system built on Pandoc that allows users to create dynamic content using R, Python, Julia, and ObservableJS (with plans to add more languages too!).

R users have long loved RMarkdown for combining prose, code, and outputs into single “knitted” documents. Quarto extends all of RMarkdown’s best features (plus many more!) to additional languages.

If you’re already an avid RMarkdown user, great news! RMarkdown (.rmd) and Quarto Markdown (.qmd) files look super similar:

  • document-level metadata and configurations are included in the document’s YAML (denoted by the --- gates at the top of the document)
  • code is written inside executable code chunks
  • prose is written in the body of the document

There are some slight differences to be aware of:

  • some YAML option names differ between the two document types (e.g. output in .rmd vs. format in .qmd)
  • chunk-level execution options are are written within with code block braces (e.g. ```{r echo=FALSE}) in .rmd files, and written below code block braces following hash pipes, |# (e.g. |# echo: false) in .qmd files
  • booleans are capitalized in YAML and chunk-level metadata in .rmd files (e.g. FALSE) and lowercase in .qmd files (e.g. false)
  • you Knit .rmd files and Render .qmd files to convert your work to your desired output type (e.g. .html)

They also look pretty similar when knitted/rendered. Below is a side-by-side comparison of a knitted .rmd file and a rendered .qmd file (both as .html files):

A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto.

Palette Art by Allison Horst. Be sure to check out the rest of Allison’s seriously cute Quarto penguin art in the #rstudioconf2022 keynote talk, Hello Quarto, by Julie Lowndes & Mine Çetinkaya-Rundel!

You can explore Quarto’s documentation to learn more about creating documents, websites, blogs, books, slides, dashboards, etc.

Create the scaffolding for your website

Before getting started…

To follow along, you’ll need:

  • R & RStudio installed
  • Quarto installed – Quarto is now included with RStudio v2022.07.1+ i.e. no need for a separate download / install if you have the latest version of RStudio
  • A GitHub account
  • Git installed / configured

Please refer to the MEDS Installation Guide for detailed setup instructions (follow steps 1-7).

A note on order of operations

This section reviews the “create remote (i.e. GitHub) repo first, then clone repo to your local machine to add Quarto website scaffolding files second” workflow. If you need / want to instead use the create a local repo with Quarto website scaffolding files first, then create upstream remote (GitHub) repo second workflow, check out these instructions.

Steps:

  1. Navigate to the GitHub profile or organization where you want your website repository (repo) to live (this will likely be the OHI-Science GitHub organization, but certainly doesn’t have to be).

  2. Create and clone a GitHub repository following the instructions, below. Importantly, choose your repo name carefully, as it’ll become a part of the website’s URL, once deployed (e.g. a repo named my-awesome-repo that lives in the OHI-Science organization will have a base URL, https://OHI-Science/my-awesome-repo).

Step-by-step instructions for creating and cloning a GitHub repo:

Create a GitHub (aka remote) repo:

  1. Click on Repositories tab in the top menu bar
  2. Click on the green New repository button in the upper right-hand corner
  3. Give it a name, and optionally, a short description. Select the radio button for Public repo (it should be selected by default). DO NOT initialize the repo with a README or .gitignore (we can add these later). Click Create repository.
  4. Copy your repo’s URL to your clipboard (currently, it’s an empty repository)

Clone your repo:

  1. Open up RStudio
  2. Click on the drop down menu next to the R project icon (top right corner)
  3. Click New Project… > Version Control > Git > paste your repo’s URL in the Repository URL: box and press Tab to auto fill the Project directory name field (it should automatically be named the same as your GitHub repo). Browse to select where on your computer you’d like your repo to be saved.
  4. Click Create Project
  1. Add Quarto website scaffolding files by running the following in your RStudio Terminal. Doing so will create the essential default website files (_quarto.yml, .gitignore, index.qmd, about.qmd, styles.css):
quarto create-project --type website
  1. Preview your site by typing quarto preview in your RStudio Terminal. This will launch a preview of your website in a browser window. So long as you leave the preview running, it will update each time you make and save changes to website files (which makes iterating on your work really easy!). By default, your repo name (here, my repo name is OHI-methods-EXAMPLE) will appear as both your navbar and landing page titles, alongside some other placeholder text. A second navbar page, titled “About”, is created for you as well.

Previewing our website in the browser by running quarto preview in the RStudio Terminal

A quick tour of our website files

When you create a new Quarto website, a handful of files are generated by default:

  1. index.qmd renders your website’s landing page. Whatever you add to this file will be the first content visitors see when they visit your site. Update the content of index.qmd (or any other website page) using markdown and / or HTML (you can mix and match both on the same page), add and execute code chunks and embed outputs, etc.
Do not change the name of index.qmd

This is the default / expected name given to website landing / home pages. If you change the name of this file, you risk breaking your (eventual) deployment.

  1. about.qmd is a regular ’ole website page. You’re able to change both the name of this file (e.g. change about.qmd to my-new-name.qmd) and / or the title of the file by updating its YAML – by default, the YAML only includes a title:
about.qmd
---
title: "About"
---

YAML is a human-readable data serialization language, which is commonly used for creating configuration files. Quarto recognizes lots of different YAML options for controlling the appearance and behavior of your individual website pages. YAML is always written at the top of a .qmd file and is denoted by a pair of “gates”, ---.

  1. _quarto.yml is your website configuration file. Any document rendered within your project directory will automatically inherit the metadata defined in this project-level configuration file (though you can control metadata on a page-by-page basis by making edits to an individual page’s YAML, which will override any options specified in _quarto.yml). Importantly, this is where you define your website’s structure (e.g. your navbar, sidebar, footer, etc.). By default, your file should look similar to this:
_quarto.yml
project: 
  type: website

website:
  title: "OHI-methods-EXAMPLE"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

  1. styles.css is a stylesheet, where you can write CSS rules to alter the appearance of your website. We’ll actually create and use a different type of stylesheet (called a “sassy css file”, .scss) in a bit.

  2. .gitignore is a place where we can specify any files that we don’t want Git to track (i.e. that we want Git to ignore). This is not a “Quarto thing,” but rather a valuable file that lives inside git directories. One common use is to add any large data files that you don’t want to accidentally push to GitHub (GitHub isn’t designed to handle LARGE files).

  3. The _site/ directory is where all of your rendered HTML (and other important) files live. When you render your site, Quarto takes all of your .qmd files and converts them to .html files, and saves them to this folder (which is important because web browsers don’t know how to read .qmd files, but do know how to read .html files). We’re actually going to change the name of this folder once we configure our website for deployment, but _site is the default name that Quarto uses (we can leave as-is, for now). You don’t want to physically edit or move any files inside this directory (if you want to make a change to your website, update the .qmd or _quarto.yml file, then re-render).

Add pages and configure your website’s navigation menus

Quarto is quite flexible, supporting a variety of website navigation options, including top navigation (navbar), side navigation (sidebar), or a combination of the two. This next section will provide examples for getting started with both navbar and sidebar navigation.

Let’s say we want to create a website that houses OHI methodology and includes pages that describe the following (this example is loosely based off the Ocean Health Index 2022: Methods document, which contains many more sections than we’ll recreate here):

  • an intro / background to the global OHI assessment
  • defining regions of interest
  • models used, including (a) regional and global index scores, (b) goal scores, and (c) likely future status dimensions
  • references

First, create some new pages

Creating new pages is as simple as adding new .qmd files to your repo (click Blank File > Quarto Document). These may live in your repo’s root directory, or you may organize them within subdirectories (though note that index.qmd should always remain in your root directory; if you organize your other pages inside a subdirectory, that subdirectory name will become a part of your URL).

Throughout this document, we’ll use the words (sub)directory and folder interchangeably.

Here, we’ll add all of our new website pages to our repo’s root directory, following these steps:

  1. Navigate to your root directory (if you’re not already there) from RStudio’s Files pane
  2. Create a new .qmd file inside your root directory by clicking Blank File > Quarto Document and giving it a name.
  3. Add any necessary YAML options to the top of each new page. For now, we’ll just add the title option for each new page.
Repeat the above steps to create each of the following .qmd files:
  • regions.qmd (with title, "Regions")
  • index-scores.qmd (with title, "Regional and global index scores")
  • goal-scores.qmd (with title, "Goal scores")
  • future-dimensions.qmd (with title, "Likely future status dimensions")
  • references.qmd (with title, "References")

At this stage, the above pages will be “hidden,” meaning that they are not accessible through our website’s navigation menu, but can be accessed using a direct link (e.g. https://OHI-methods-EXAMPLE/regions.html, localhost:XXXX/regions.html). Our next important step is to add them to our website’s navigation menu in _quarto.yml – how this looks will depend on which type of navigation (e.g. navbar, sidebar) menu we want. See more below!

Top navigation (navbar)

By default, Quarto creates a website with a navbar. Here, we’ll add our new files to our navbar. We can also remove files from our navbar by commenting them out or deleting them completely (e.g. here, I removed about.qmd, which was there by default; until I delete about.qmd from the repo entirely, it’ll remain a hidden page):

_quarto.yml
project:
  type: website

website:
5  navbar:
    title: "OHI-methods-EXAMPLE"
1    left:
2      - href: index.qmd
        text: Home
3      - regions.qmd
4      - text: Models
        menu:
          - index-scores.qmd
          - goal-scores.qmd
          - future-dimensions.qmd
      - references.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
1
(NOTE: click on the number to the left to highlight the corresponding line(s) of code, above!) Set your navbar pages on the left or right
2
By default, the navbar page name is the same as the title set in that .qmd’s YAML. If you want the navbar page name to be different than the page title, declare the navbar page name using text.
3
Newly added navbar pages
4
A navbar item with sub menu pages
5
Note: I removed my site-level title option and added it instead as a navbar title. Functionally, they appear the same way, but organizationally I think this makes more intuitive sense (my title lives inside my navbar (or sidebar)). This new positioning is also important if we decide to add both a website title and logo (we’ll explore this in a later section).

Newly added navbar pages. Clicking on the “Models” navbar item reveals a sub menu of pages.

Side navigation (sidebar)

A sidebar is a great option if you have lots of documents which require a deep hierarchy of pages. Setting up a sidebar looks very similar to creating a navbar, with the exception of a few slightly different YAML option names:

_quarto.yml
project:
  type: website

website:
1  sidebar:
    title: "OHI-methods-EXAMPLE"
2    style: "docked"
3    search: true
4    contents:
      - href: index.qmd
        text: Home
      - regions.qmd
      - section: Models
5        contents:
          - index-scores.qmd
          - goal-scores.qmd
          - future-dimensions.qmd
      - references.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
1
Specify sidebar, rather than navbar
2
Choose from "docked" or "floating"
3
Remove search bar by setting style to false
4
All top level pages or sections fall under this first contents section
5
Create a sub menu by adding contents beneath a section header

Newly added sidebar pages with the “Models” section expanded to reveal sub menu pages.

Where sidebars really shiny is when you want to create additional nested sub menus – let’s say we want to recreate this sub menu as it appears in the Ocean Health Index 2022: Methods document. We’ll need to add a few more pages, first (see below).

Add more pages (.qmd files) before creating the next nested sub menu

Add the following pages to your repo’s root directory:

  • trend.qmd (with the title, "Trend")
  • pressure.qmd (with the title, "Pressure")
  • resilience.qmd (with the title, "Resilience")

Now, add your three new pages as sub menu items beneath the section header, Likely future status dimensions:

_quarto.yml
project:
  type: website

website:
  sidebar:
    title: "OHI-methods-EXAMPLE"
    style: "docked" 
    search: true
    contents: 
      - href: index.qmd
        text: Home
      - regions.qmd
      - section: Models
        contents: 
          - index-scores.qmd
          - goal-scores.qmd
1          - section: Likely future status dimensions
            contents:
              - trend.qmd
              - pressure.qmd
              - resilience.qmd
      - references.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
1
Here, we converted the old future-dimensions.qmd into a section header with the same title, Likely future status dimensions. Expanding it reveals its contents – three new pages, Trend, Pressure, and Resilience.

Newly added section titled, “Likely future status dimensions.” Expanding this section reveals our three new pages, “Trend,” “Pressure,” and “Resilience.”

We can continue to add additional sub menus following the pattern above.

Learn more

This was only a brief introduction to website navigation! Check out the Quarto documentation for more details, options, and examples.

Additional _quarto.yml configurations

The _quarto.yml file is a place to make lots of additional updates to website appearance / configurations. Here, we’ll review just a few places to make easy and valuable updates, but be sure to check out the Quarto documentation for additional available tooling options.

Updating website title, table of contents, and page layout

Add content to your landing page (index.qmd) before continuing on!

Before we make updates to _quarto.yml, let’s add some background information to our landing page, index.qmd (the below text was copied directly from Ocean Health Index 2022: Methods). We can also update our page title to something more informative than our repo name (which is set by default):

---
title: "Ocean Health Index 2024: Methods"
---

## Introduction to the global Ocean Health Index (OHI) assessment

The global Ocean Health Index assesses ocean health for 220 coastal countries and territories and has been conducted every year starting in 2012. The Index describes how well we are sustainably managing 10 goals for ocean ecosystems which represent the full suite of benefits that people want and need from the ocean. These goals include: artisanal fishing opportunity, biodiversity, carbon storage, clean waters, coastal livelihoods and economies, coastal protection, food provision, natural products, sense of place, and tourism and recreation. Each goal is given a score ranging from 0 to 100, and the full suite of goal scores are then averaged to obtain an overall index score for each region.

For more information about the philosophy of the Ocean Health Index and model development see Halpern et al. (2012, 2015) and <http://ohi-science.org/ohi-global/>, which includes information about downloading global ocean health data.

The website should look similar to this, when previewed:

Our new landing page, with an updated title and text.

A few adjustments to our _quarto.yml can improve our website’s appearance:

_quarto.yml
project:
  type: website

website:
  sidebar:
1    title: "OHI Methods (2024)"
    style: "docked" 
    search: true
    contents: 
      - href: index.qmd
        text: Home
      - regions.qmd
      - section: Models
        contents: 
          - index-scores.qmd
          - goal-scores.qmd
          - section: Likely future status dimensions
            contents:
              - trend.qmd
              - pressure.qmd
              - resilience.qmd
      - references.qmd

format:
  html:
    theme: cosmo
    css: styles.css
2    toc: false
3    page-layout: full
1
Update the website title
2
Remove Table of Contents from all pages (though you can enable TOC on a page-by-page basis by setting toc: true in the YAML of individual .qmd files)
3
Allow text / content to fill the entire page – read more on page layout options

After these three small updates, our website now looks like this:

Adding a page footer (and embedding FontAwesome icons!)

Add a page footer beneath the website option in _quarto.yml – you’ll want the page-footer option to be indented in the same was as sidebar:

_quarto.yml
project:
  type: website

website:
  sidebar:
    # title: "OHI Methods (2024)"
    logo: media/OHI-logo.png 
    style: "docked" 
    search: true
    contents: 
      - href: index.qmd
        text: Home
      - regions.qmd
      - section: Models
        contents: 
          - index-scores.qmd
          - goal-scores.qmd
          - section: Likely future status dimensions
            contents:
              - trend.qmd
              - pressure.qmd
              - resilience.qmd
      - references.qmd
1  page-footer:
    left: Learn more about the [Ocean Health Index](https://oceanhealthindex.org/) 
2    right: Source code available on [{{< fa brands github title="the GitHub octocat" >}} GitHub](https://github.com/samanthacsik/OHI-methods-EXAMPLE)

format:
  html:
    theme: cosmo
    css: styles.css
    toc: false
    page-layout: full
1
Anything that you’d like to place in your website footer should be included under the page-footer option. Content can be placed on the left, right, or center of the footer.
2
We can install the fontawesome extension to embed icons, like the GitHub logo here, throughout our website. See the tip below for more information!

Our newly added website footer!


Install the fontawesome Quarto extension to use any free FontAwesome icons

Run the following in your RStudio Terminal to install the extension:

quarto add quarto-ext/fontawesome

The extension files will be saved to a folder named _extensions in your repo’s root directory. Be sure to push this new folder (and its contents) to GitHub.

To embed an icon, look up the icon’s name on FontAwesome (be sure to only choose from the Free icons), then use the fontawesome shortcode:

{{< fa icon-name title="descriptive text for accessibility" >}}

For example, the following shortcodes…

{{< fa face-smile title="A smiling face" >}}
{{< fa laptop title="An open laptop" >}}
{{< fa file-code title="A code file" >}}

…will render as these icons: , ,

Some icons fall within the brands collection and must be prefixed with brands inside the shortcode. For example, the GitHub icon :

{{< fa brands github title="The GitHub octocat logo" >}}

You can identify if an icon falls within the brands collection by clicking on its preview (e.g. the github icon) and checking to see if the HTML class is fa-brands:

Build & publish your website using GitHub Pages

There are a lots of options to publish your website. We’ll use the GitHub Pages option, which allows you to publish a website from any GitHub repository. To do so, there are a few configuration steps:

  1. Create a file named .nojekyll in your repository’s root directory (e.g. OHI-methods-EXAMPLE/), which is required to disable some processing of HTML files that GitHub does by default. There are two ways you can do this:

    1. In your RStudio Terminal, type the following command:
    touch .nojekyll
    1. From RStudio’s File pane, click New Blank File > Text File, then type in .nojekyll.

The touch command can be used to create a new, empty file from the command line. Similarly, RStudio’s Text File button allows you to define and create any file type. Since there’s no default button in RStudio for creating a .nojekyll file, you’ll want to use one of these two approaches.

.nojekyll is a hidden file which won’t visibly appear in your directory. You should see it show up as a file to track with git (either under the Git tab in RStudio, or when you run git status in the command line). You can also view hidden files in Finder (Mac) using the keyboard shortcut Command + Shift + ., or follow these instructions for Windows 10, 8.1, and 7.

  1. Set the output-dir in your _quarto.yml file to docs (it’s easiest to open and edit this from RStudio):
_quarto.yml
project:
  type: website
  output-dir: docs
  
# ~ additional metadata excluded for brevity ~

The output-dir is the directory (i.e. folder) where your rendered .html (and other important) files will automatically be saved to when you “Build” your website (see the next step!) – that is, when you convert all your .qmd files to the .html files that your web browser can interpret / display.

You can delete _site/ if it exists and if you’re publishing with GitHub Pages

If you previewed or built your site before setting output-dir to docs in _quarto.yml, you’ll notice a _site/ directory inside your repository – this is the default output directory name. Because GitHub Pages will expect a docs/ folder to deploy from, you can delete _site/ altogether (and push your deletion, if you’ve already committed / pushed _site/ to GitHub).

  1. Build / render your website. Click on the Build tab (top left pane in RStudio if you have the default layout), then Render Website (alternatively, you can run quarto render in the Terminal) – this command creates the final version of your website documents for deployment. Once rendered, you should see your soon-to-be website appear in the Viewer tab.
Close / reopen your project if the Build tab is missing

If you don’t see the Build tab, close then reopen your project. It should appear!

You MUST render your website before pushing your files to GitHub!

Clicking Render Website in the Build tab (or running quarto render in the Terminal) is a necessary pre-(re)deployment step – it converts all .qmd files to .html and ensures that all website components are stitched together correctly. If you do not render your website before pushing your files, your changes will not deploy.

  1. Send all of your website files from your local git repository to your remote GitHub repository:

    1. Stage your files by checking all the boxes in the Git tab (this is analogous to the git add . command used in the Terminal for staging all files)
    2. Commit your files by clicking the Commit button, adding a commit message, and clicking “Commit” (analogous to git commit -m "my commit message")
    3. Push your files to the remote repository (on GitHub) by clicking the “Push” button with the green upward facing arrow (analogous to git push).

  2. Configure GitHub pages to serve content from the “docs” directory by clicking on the Settings tab in the top menu bar, then the Pages tab from the left-hand menu bar. Make sure that Branch is set to main and that the selected folder is set to /docs. Click Save. Once deployed (this may take a few minutes), your website’s URL will appear inside a box at the top of the page (you may have to try refreshing a few times).

Your website’s URL will appear at the top of the page once you’ve configured GitHub pages to host your Quarto site

A hosted Quarto website! Now time to customize and add content.
Check out the Actions tab on GitHub to view deployment status

See deployment status, time of each deployment, and how long it took to deploy each run. You can also find failed deployments here (yes, it does happen on occasion) and take action on fixing them.

You’re now ready to continue iterating on your website and redeploy with ease! Your workflow will look something like this:

  1. Make updates to your website in RStudio (or IDE / text editor of choice)
  2. Re-render your website by either (a) clicking Render Website in RStudio’s Build tab, or (b) running quarto render in the Terminal
  3. Push all of your files to GitHub where GitHub Pages will re-deploy your site with your latest changes

Updating colors & fonts using Sass

There are a number of ways to update a Quarto website’s theme (e.g. colors, fonts), but the (arguably) fastest and easiest way to get started is by defining some Sass variables in a .scss file (stylesheet), then linking to that stylesheet in your _quarto.yml metadata. The steps below offer a “quick start guide approach,” though I recommend checking out these workshop materials on customizing Quarto websites using Sass & CSS for a much more thorough / deeper dive.

Create and apply a .scss file / stylesheet

  1. Create a styles.scss file in your repo’s root directory (you can name it however you’d like), using the command touch styles.scss in the Terminal, or by Blank File > Text File > typing styles.scss from the RStudio Files pane.

  2. Add the /*-- scss:defaults --*/ region decorator to the top of styles.scss (required by Quarto) – you’ll write all your Sass variables underneath this:

styles.scss
/*-- scss:defaults --*/
  1. Apply your styles.scss stylesheet to your website using the theme option in _quarto.yml:
_quarto.yml
project:
   # ~ additional YAML omitted for brevity ~

website:
  # ~ additional YAML omitted for brevity ~
  
format:
  html:
1    theme: styles.scss
    toc: false
    page-layout: full
1
Apply your styles.scss stylesheet using the theme option

This tutorial doesn’t cover writing CSS, though you can (and should) write any CSS in your .scss file (rather than writing it in a separate .css file). I recommend removing styles.css from _quarto.yml. You can also delete styles.css from your repo (you can always create a new one if you decide you want / need a .css file in the future).

Update website colors

  1. Define some color variables using the syntax, $variable-name: value; (you get to decide what these variable names are!). Here, we define three colors:
styles.scss
// Colors
$baby-blue: #E3F1F2;
$dark-blue: #252D5C;
$orange: #F26C25;
Use // for single line comments in .scss files

You may also create multi-line comments, which start with /* and end at the next */.

  1. Use your color variables as values for Quarto’s Sass variables. Below, we specify only four, however there are a number of Sass variables which can be defined within SCSS files (find a list of them here):
styles.scss
/*-- scss:defaults --*/

// Colors
$baby-blue: #E3F1F2;
$dark-blue: #252D5C;
$orange: #F26C25;

// Sass vars
$body-bg: $baby-blue;
$body-color: $dark-blue; 
$link-color: $orange; 
$footer-bg: $dark-blue;

Your newly styled site should look similar to this (be sure to run quarto preview in the Terminal, if it’s not already running).

Update website fonts

  1. Find a Google font family by browsing options at https://fonts.google.com/. There are so many options – click on the Filter button in the top left corner of the page to help narrow your choices. For this exercise, we’ll go with Nunito (my personal favorite).
If you want to bold or italicize text, you need to select a font family that has those styles

Not all font families come in every style. For example, Nunito comes in a variety of weights (i.e. levels of boldness) and italic, while Sen comes in a variety of weights, but not italic. This means that if you import and use Sen, you will not be able to italicize text.

  1. Select a Google font family(ies) by clicking the blue Get Font button in the top right corner of the page, which adds your font family to your “bag.” You can add as many font families to your bag as you’d like to import, though we’ll stick with just one (Nunito) for this exercise. Click Get embed code, then choose the @import radio button (beneath the Web menu option), which will provide your import code chunk. Copy everything between the <style> </style> tags (starting with @import and ending with ;) to your clipboard.

  1. Import your Google font by pasting the import code into styles.scss (I always place this at the top of my stylesheet, beneath /*-- scss:defaults --*/):
styles.scss
/*-- scss:defaults --*/

// Import Google fonts
@import url('https://fonts.googleapis.com/css2?family=Nunito:ital,wght@0,200..1000;1,200..1000&display=swap');

// Colors
$baby-blue: #E3F1F2;
$dark-blue: #252D5C;
$orange: #F26C25;

// Sass vars
$body-bg: $baby-blue;
$body-color: $dark-blue; 
$link-color: $orange; 
$footer-bg: $dark-blue;
  1. Apply your font using the mainfont option in _quarto.yml – this is the easiest way to use a single font across your entire website:
project:
  # ~ additional YAML omitted for brevity ~

website:
  # ~ additional YAML omitted for brevity ~

format:
  html:
    theme: styles.scss
    toc: false
    page-layout: full
1    mainfont: Nunito
1
Be sure to spell the font family name exactly as it appears on Google Fonts

Our updated website, with Nunito applied.

You can totally import and use more than one Google font!

But this requires a bit more Sass and CSS. While we won’t get into that here, check out these workshop materials and some “in the wild” examples (e.g. like the stylesheet for this very instructional document ).

Don’t forget to Render Website and push your files back to GitHub, when finished!

GitHub Pages will then rebuild and redeploy your site at your URL.

Additional resources & tips

  • New to Markdown or need a refresher? Review the most commonly used markdown syntax.
  • Quarto will automatically generate citations and a bibliography in a number of styles(!!) – check out the official documentation. I also provide some examples, screenshots, and explanations in this blog post.
  • Take inspiration from other Quarto websites (and explore their source code)! See something you want to recreate but don’t know how? Check out the GitHub repo (which is often linked somewhere on the website). Here are a couple other Quarto websites I’ve created, which take advantage of custom layouts and other fun Quarto features:


Banner image: Photo © Cingular | Shutterstock