Lecture 7: Customizing Quarto Websites

BAA1028 - Workflow & Data Management

Damien Dupré

Existing Quarto Websites

Requirement

You should already have a Quarto website (or at least the bones of one) that:

is deployed using GitHub Pages and
contains some content (e.g. text, headings, etc.) for us to customize

Beside these slides, have a look at the GitHub Repository “Awesome Quarto” for more support and examples.

Quarto Website Default Design

When we render a new Quarto site, it converts all of our markdown into HTML and applies a pre-built CSS stylesheet (the Bootswatch Cosmo theme).

We can modify the appearance of our website in a number of ways:

Editing the index.qmd YAML – you can apply a pre-built template to give your landing page a sleek and professional appearance (we can further modify this later with some CSS).
Editing the _quarto.yml file – this is our website configuration file, where we can easily update our website’s navigation (e.g. add new pages), add a page footer, a favicon, and much more. We can also switch the default theme to a different pre-built Bootswatch theme (by replacing cosmo with an alternative theme name).
Defining CSS rules in the styles.css file that comes with every new Quarto site. This allows you to fine-tune the appearance of your site.
Creating a .scss file(s) that contains Sass variables to quickly customize your website’s theme – these take the form of $var-name: value; and you can find a list of them in the Quarto documentation.
Or…

Quarto Website Default Design

Combine all of the above!

Approaching this in the following order worked best for me:

First, add a pre-built template to index.qmd and adjust website configurations by editing _quarto.yml – this is the easiest way to add some really cool features with minimal effort.
Next, create a styles.scss file, link to it in _quarto.yml (this applies your styles to your Quarto site), and define your Sass variables.
Finally, make fine-tuned adjustments by defining CSS rules directly in your styles.scss file (you can write CSS in .scss files, but not Sass in .css files).

Preview your site for fast iteration

Run quarto preview in the VS Code Terminal to view changes in near real time – each time you edit and save your work, the preview will update in your browser.

Note: this is RStudio but it would be the same with VS Code

Quarto Pre-Built Templates

So you’ve created a Quarto website…

Quarto gives us an easy-to-use web publishing format to create our personal websites, that we can develop in a space that is comfortable (VS Code) and write mostly Markdown syntax (which is rendered as HTML when we build our website).

A massive benefit is that these websites already look pretty slick right out of the box.

This page is an example Quarto website styled using the built-in Bootswatch theme Cosmo and the jolla layout template applied.

Edit YAML

Adding a pre-built template to index.qmd and adjusting website configurations by editing _quarto.yml is the easiest way to add some really cool features with minimal effort.

You can apply a template to any of your website’s pages, though they are particularly awesome for creating a clean, professional-looking landing page.

Edit YAML

Quarto includes 5 built in templates, drawing inspiration from the Postcards R Package. Built-in templates include:

jolla
trestles
solana
marquee
broadside

Edit YAML

Each template will position the about elements with the content in a different layout. Select the template using the template option:

---
about:
  template: trestles
---

Edit YAML

Here is a preview of each of the templates:

jolla
trestles
solana
marquee
broadside

Edit YAML

The image for the about page will be read from the document-level image option:

---
title: Finley Malloc
image: profile.jpg
about:
  template: jolla
---

Edit YAML

In addition, you can customize how the image is displayed in the page to better meet your needs by setting the following options.

option	description	templates
`image-width`	A valid CSS width for your image.	all
`image-shape`	The shape of the image on the about page. Choose from:`rectangle`, `round`, `rounded`	`jolla`, `solana`, `trestles`
`image-alt`	Alternative text for image	all
`image-title`	Title for image	all

For example:

---
title: Finley Malloc
image: profile.png
about:
  template: trestles
  image-width: 10em
  image-shape: round
---

Edit YAML

Your about page also may contain a set of links to other resources about you or your organization.

Each template will render these links in a slightly different way. Here are the options that you can specify for each link:

Option	Description
`href`	Link to file contained with the project or an external URL.
`text`	Text to display for navigation item (defaults to the document `title` if not provided).
`icon`	Name of one of the standard Bootstrap 5 icons (e.g. “github”, “twitter”, “share”, etc.).
`aria-label`	Accessible label for the navigation item.

Add a landing page template

Here is an example:

Without an About Page template

jolla About Page template

Add a landing page template

And the corresponding code

---
# title: "Samantha Csik" # optional (omitted in example screenshots)
image: file/path/to/headshot.jpeg # a great spot for your professional headshot :) 
toc: false # disable table of contents for this page (if applicable)
about: 
  template: jolla 
  image-shape: round
  image-width: 17em
  links: # create buttons
    - text: LinkedIn
      href: https://www.linkedin.com/in/samanthacsik/
      target: _blank # opens link in a new browser tab
    - text: GitHub
      href: https://github.com/samanthacsik
      target: _blank 
    - text: Email
      href: mailto:scsik@ucsb.edu
---
        
# ~ landing page content / text omitted for brevity ~

FontAwesome Icons

Add any free FontAwesome icons to your buttons using the icon option. For example:

---
# ~ additional YAML excluded for brevity ~
  links: 
    - icon: linkedin 
      text: LinkedIn
      href: https://www.linkedin.com/in/yourlinkedinname/
      target: _blank
---

Be sure to spell the icon name exactly as it appears on FontAwesome’s website (e.g. the LinkedIn icon, , is all lowercase and spelled, linkedin).

Exercise 1: Quarto Template

Use one of the templates (i.e., jolla, trestles, solana, marquee, or broadside) in a page of your website (i.e., index.qmd, about.qmd, or any other page).

Remember, you need to change the yaml of your page as follow:

---
image: relative/path/to/your/image.jpg
about:
  template: jolla
  links: # create buttons
    - icon: linkedin 
      text: LinkedIn
      href: https://www.linkedin.com/in/yourname/
---

10:00

Customise `_quarto.yml`

Add / arrange pages

We can configure website navigation in _quarto.yml, including the type of navigation menu (navbar, sidebar), how pages are ordered, etc.

Here, the navbar items have been moved to the right side, link to a curriculum vitae (pdf), and also add a GitHub icon which links to a GitHub profile.

Add / arrange pages

Make edits to a website’s navigation bar under the website > navbar option:

_quarto.yml

project:
  type: website
  output-dir: docs

website:
  title: "Sam Csik"
  navbar:
    right: # accepts right/left/center; you can also place items individually on the left, right, and center
      - href: index.qmd
        text: Home
      - about.qmd
      - href: resources.qmd
        text: Resources
      - href: file/path/to/myCV.pdf # provide a relative file path to a pdf will open up a browser-based pdf viewer when clicked
        text: CV
        target: _blank # opens link (or page) in a new browser tab
      - icon: github # add icons as navbar buttons
        href: https://github.com/samanthacsik
        target: _blank

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
    page-layout: full

Add page footer

Make edits to a website’s footer under the website > page-footer option:

_quarto.yml

project:
  type: website
  output-dir: docs

website:
  title: "Sam Csik"
  navbar:
    right:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: resources.qmd
        text: Resources
      - href: cv/myCV.pdf
        text: CV
        target: _blank 
      - icon: github 
        href: https://github.com/yourUserName
        target: _blank
  page-footer:
    background: light #or dark
    left: Copyright 2021, Samantha Csik
    right: This website is built with , [](https://github.com/samanthacsik/samanthacsik.github.io){target=_blank}, [](https://www.r-project.org/about.html){target=_blank} and [Quarto](https://quarto.org/){target=_blank}

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
    page-layout: full

FontAwesome Extension

If you want to use FontAwesome icons anywhere else on your website (i.e. outside of the icon YAML option), you’ll need to first install the Quarto fontawesome extension.

Running the following in your Terminal will download and save the extension to a folder named _extensions in your repo’s root directory.

Make sure you’re in your project’s root directory and don’t forget to push this new folder (and its contents) to GitHub:

Terminal

quarto add quarto-ext/fontawesome

Note: You’ll need to install this extension for each new project where you’d like to use icons (e.g. if you create a different website).

FontAwesome Shortcode

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 >}}

For example, the following shortcodes…

{{< fa face-smile >}}
{{< fa laptop >}}
{{< fa file-code >}}

…will render as , ,

FontAwesome Brands

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

{{< fa brands github >}}

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:

Favicons and Logos

You can add a personal logo in the top left corner of your navbar in place of your title. The free Adobe Express Logo Maker is a great tool for creating your own logo!

Tip: Download your logo with a transparent background so that it can be placed anywhere on your site without having to deal with mismatched background colours. I also recommend making them as large as possible before downloading to mitigate the need for drastic resizing using CSS.

Favicons and Logos

A favicon is a small icon used on web browsers to represent a website or a web page. Get creative and use a custom favicon that complements your personal logo.

Favicons and Logos

Design Your Favicon to be simple and recognisable, as favicons are small (usually 16x16 or 32x32 pixels). Common formats include .ico, .png, and .svg.
Generate the Favicon using an online generator. Websites like https://favicon.io/ or https://realfavicongenerator.net allow you to upload an image and generate a .ico file and the necessary sizes for various devices.
Add the Favicon to Your Website

_quarto.yml

website:
  title: "Sam Csik"
  favicon: file/path/to/image.png

Favicons and Logos

_quarto.yml

project:
  type: website
  output-dir: docs

website:
  title: "Sam Csik"
  favicon: file/path/to/image.png # NOTE: that the `favicon` is a `website` level option (not under `navbar`)
  navbar:
    title: false # override printing your website `title` (e.g. "Sam Csik" on line 6) in the top left corner of your navbar
    logo: file/path/to/logo.png
    right:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: resources.qmd
        text: Resources
      - href: file/path/to/myCV.pdf
        text: CV
        target: _blank
      - icon: github
        href: https://github.com/samanthacsik
        target: _blank
  page-footer:
    background: light
    left: Copyright 2021, Samantha Csik
    right: This website is built with , [](https://github.com/samanthacsik/samanthacsik.github.io){target=_blank}, [](https://www.r-project.org/about.html){target=_blank} and [Quarto](https://quarto.org/){target=_blank}


format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
    page-layout: full

Website Tools

Explore Quarto’s documentation to learn more about enabling Google Analytics, Open Graph protocol, and more.

Exercise 2: Favicons and Logos

Create a logo and a favicon using Adobe Express Logo Maker and favicon.io/realfavicongenerator.net

Add them to your _quarto.yml using a relative path.

_quarto.yml

website:
  title: "Your Title"
  favicon: file/path/to/image.png 
  navbar:
    title: false
    logo: file/path/to/logo.png

10:00

References

Huge thanks the following people who have generated and shared most of the content of this lecture:

Sam Csik: Customizing Quarto Websites, Make your website stand out using SASS and CSS

Thanks for your attention and don’t hesitate to ask if you have any questions!
@damien_dupre
@damien-dupre
https://damien-dupre.github.io
damien.dupre@dcu.ie

Lecture 7: Customizing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

Requirement

Quarto Website Default Design

Quarto Website Default Design

Preview your site for fast iteration

Quarto Pre-Built Templates

So you’ve created a Quarto website…

Edit YAML

Edit YAML

Edit YAML

Edit YAML

Edit YAML

Edit YAML

Edit YAML

Add a landing page template

Add a landing page template

FontAwesome Icons

Exercise 1: Quarto Template

Customise _quarto.yml

Add / arrange pages

Add / arrange pages

Add page footer

Add page footer

FontAwesome Extension

FontAwesome Shortcode

FontAwesome Brands

Favicons and Logos

Favicons and Logos

Favicons and Logos

Favicons and Logos

Favicons and Logos

Website Tools

Exercise 2: Favicons and Logos

References

Customise `_quarto.yml`