Lecture 6: Quarto for Website Creation

BAA1028 - Workflow & Data Management

Damien Dupré

For Today

Requirements:

✅ Having Git Installed and its Config done
✅ Having VS Code Installed with all required Extensions installed
✅ Having Quarto Installed and Properly Working
✅ GitHub Account Created

Programme

Creating your Quarto Website
Push it to GitHub
Activating GitHub Pages

Any questions?

Create a website with Markdown

Quarto Websites

Quarto Websites are a convenient way to publish groups of documents. Documents published as part of a website share navigational elements, rendering options, and visual style.

Website navigation can be provided through a global navbar, a sidebar with links, or a combination of both for sites that have multiple levels of content. You can also enable full text search for websites.

Your Turn: Quarto Website

Open VS Code, open a new Terminal window in VS Code and run the following instructions to create a new Quarto website by using your GitHub username + .github.io (e.g. damien-dupre.github.io):

Terminal

quarto create project website your-github-username.github.io

When asked for the name of your website, use your name (e.g. Damien Dupré), and then:

Terminal

quarto preview

03:00

Quarto Websites

Terminal

quarto create project website your-github-username.github.io

This creates a new website project from the Terminal. This website project is initiated by a folder called your-github-username.github.io located on the root of your terminal.

The folder contains only 4 files:

_quarto.yml is a yaml file, it design the overall style and the navbar
index.qmd is a quarto file, it corresponds to the homepage
about.qmd is another quarto file which is displayed when about is clicked on the navbar
styles.css is for additional style not defined in _quarto.yml

Quarto Websites

Improve your Website:

Navigation instructions here: https://quarto.org/docs/websites/website-navigation.html
Option instructions here: https://quarto.org/docs/reference/projects/websites.html

Quarto Websites

Terminal

quarto preview

This command is used to render the website by converting all the .qmd files to .html files stored in a _site folder.

The website preview will open in a new web browser. As you edit and save index.qmd (or other files like about.qmd) the preview is automatically updated.

Publish this website on GitHub

Overview

There are three ways to publish Quarto websites and documents to GitHub Pages:

Render sites on your local machine to the docs directory, check the rendered site into GitHub, and then configure your GitHub repo to publish from the docs directory.
Use the quarto publish command to publish content rendered on your local machine.
Use a GitHub Action to automatically render your files (a single Quarto document or a Quarto project) and publish the resulting content whenever you push a source code change to your repository.

The simplest way to publish using GitHub Pages is to render to the docs directory and then upload that directory into your repository…

Overview

… but it won’t be as easy as it looks I’m afraid!

Render the Website docs Folder

In the _quarto.yml file, simply change the output directory folder to a folder named docs as follow:

_quarto.yml

project:
  type: website
  output-dir: docs

Then, render the website:

Terminal

quarto render

Add a .nojekyll File

Add a .nojekyll file to the root of your repository that tells GitHub Pages not to use Jekyll (the GitHub default site generation tool).

Important

Jekyll ignores files and folders that start with an underscore. Many modern static site tools like Quarto, Hugo, or plain build pipelines generate folders such as _site or _resources. When Jekyll runs, those folders can be silently dropped, which breaks the site.

You can create it from the terminal when the website folder is the current directory:

Bash or zsh

touch .nojekyll

CMD

type nul > .nojekyll

PowerShell

ni .nojekyll

Render the Website docs Folder

Your website default folder should look like that

Note: the old folder _site will not be used any more and is now useless.

Your Turn: Your Quarto Website in GitHub

Add a .nojekyll File:

Terminal

touch .nojekyll # Bash or zsh
type nul > .nojekyll # CMD
ni .nojekyll #PowerShell

Change the output directory folder to a folder named docs in the _quarto.yml file:

_quarto.yml

project:
  type: website
  output-dir: docs

Then, render the website

Terminal

quarto render

In the Source Control panel, click Initialize Repository, add all files by clicking on +, add a mandatory message and click ✔️ Commit. Finally, click Publish Branch
In GitHub, click Settings -> Pages choose:

main branch
/docs folder
and Save

10:00

Existing Quarto Websites

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).

Your Turn: 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.

Your Turn: 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 6: Quarto for Website Creation

For Today

Requirements:

Programme

Any questions?

Create a website with Markdown

Quarto Websites

Your Turn: Quarto Website

Quarto Websites

Quarto Websites

Quarto Websites

Publish this website on GitHub

Overview

The simplest way to publish using GitHub Pages is to render to the docs directory and then upload that directory into your repository…

Overview

… but it won’t be as easy as it looks I’m afraid!

Render the Website docs Folder

Add a .nojekyll File

Render the Website docs Folder

Your Turn: Your Quarto Website in GitHub

Existing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

Existing Quarto Websites

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

Your Turn: 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

Your Turn: Favicons and Logos

References

Customise `_quarto.yml`