Lecture 6: Advanced 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

  1. Creating your Quarto Website
  2. Push it to GitHub
  3. Activating GitHub Pages

Any questions?

Create a website with Markdown and Python Code embedded

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.

Exercise 1: Quarto Website

  1. Open VS Code, open a new Terminal window in VS Code and run the following instructions:
Terminal
cd ~
mkdir Project
cd Project
  1. Create a new Quarto website from the same terminal 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
05:00

Quarto Websites

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

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:

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.

.qmd Files

Unfortunately .ipynb files cannot be used to build a website.

Thankfully they can be converted to .qmd format by quarto with the instruction:

Terminal
quarto convert myfile.ipynb

.qmd files are actually very similar to .ipynb files and are tailored for quarto:

  • They have a yaml displayed between two series of --- signs
  • They have markdown text
  • They can have code cell, also called chunks

.qmd Files

Chunks are delimited by 3 backticks on each end ``` followed by the engine (python) between curly braces {python}

```{python}
print('Hello, world!')
```

Exercise 2: Convert a Notebook to .qmd

  1. Open a new Terminal window in VS Code and run the following instructions:
Terminal
quarto convert hello.ipynb
  1. Drag and drop the file hello.qmd created in the root of the your-github-username.github.io folder
  1. Open the file _quarto.yml in Jupyter and modify it as follow:
_quarto.yml
website:
  title: "Damien Dupré"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - hello.qmd
  1. In the same Terminal window, run the following instructions:
Terminal
quarto preview
10:00

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 preview or render the website:

Terminal
quarto render
Terminal
quarto preview

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.

Add a .nojekyll File

Add a .nojekyll file to the root of your repository that tells GitHub Pages not to do additional processing of your published site using Jekyll (the GitHub default site generation tool).

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

Terminal
touch .nojekyll

Upload your Files to GitHub

When GitHub suggests ways how to upload files, it gives instructions to create a new repository on the command line with git.

For example:

Terminal
cd your-github-username.github.io #if not done yet
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/your-github-username/your-github-username.github.io.git
git push -u origin main

You should see all your files uploaded in your GitHub repository

Exercise 3: Your Quarto Website in GitHub

  1. Add a .nojekyll File:
Terminal
touch .nojekyll
  1. Change the output directory folder to a folder named docs in the _quarto.yml file:
_quarto.yml
project:
  type: website
  output-dir: docs

Then, preview or render the website

Terminal
quarto render

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

  2. In GitHub, click Settings -> Pages choose:

  • main branch
  • /docs folder
  • and Save
10:00

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