Practical example

Create a static website with Quarto

Author

Ludovic Deneuville

Published

September 20, 2023

Introduction

You will learn how to create your first static website with Quarto.

1 GitHub repository

To publish our website, we will use GitHub Pages. The first step is to create a repository on GitHub.

Log in to GitHub
Create a new repository called Quarto-practical
- Visibility : Public
- check Add a README file
- .gitignore : GitHubPages
- licence : Creative Commons Zero v1.0 Universal
Create a new branch called gh-pages
- clic on button main
- write gh-pages
- clic on Create branch gh-pages from main
- wait 30 seconds and then refresh the page until a Deployments section appears at the bottom right

Why deploy from pages branch gh-pages ?

This will keep your branch main clean and avoid including html pages generated by Quarto :

branch main : setup and content in qmd files
branch gh-pages : html for deployment

In the About section clic on ⚙️
- Check Use your GitHub Pages website
- Save changes

You can clic on the url. Your website is created but empty.

2 Local repository

We will use the IDE Visual Studio Code to edit our pages.

Login to SSPCloud
launch a service Vscode-r-python-julia
Open a bash terminal
- terminal > New terminal or CTRL + ù or CTRL + SHIFT + C
Clone the repository Quarto-practical using HTTPS
Open Folder Quarto-practical
- File > Open Folder > /home/onyxia/work/Quarto-practical
Once again, open a bash terminal

Licence

The license chosen in GitHub is too permissive. Let’s change it for a more restrictive one

Paste the text of licence CC BY-NC-SA 4.0 in file LICENCE
- BY (Attribution): Credit must be given to the creator
- NC (Non Commercial): Only noncommercial uses of the work are permitted
- SA (Share Alike): Adaptations must be shared under the same terms

More about Creative Commons licences

3 Create a Quarto project

Let’s start by creating a quarto project. We’re going to create a website project, i.e. a collection of web pages.

quarto create project
- Type: website
- Directory: .
- Title: My first quarto site

This command will create the following files in the current directory (.):

_quarto.yml: metadata
index.qmd: the home page
about.qmd: another page (not a mandatory file)
styles.css: to customize visual aspects of your Quarto website

Note

It is also possible to create these files manually.

4 Preview your site

quarto preview

You can open the preview on a specific port.

Click on Open in Browser

Tip

CTRL + C to quit the preview

5 Edit your files

Now it’s time to custom our website.

5.1 index.qmd

Let’s modify the index:

adding some local metadata (between ---)
inserting link to other pages
putting an emoji

---
title: "Quarto-practical"
description: "Let's have fun with Quarto"
author: "Me"
format: html
from: markdown+emoji
---


## Quarto 

- [External link to Quarto website](https://quarto.org/){target="_blank"}
- [R example](doc/r.qmd)
- [Python example](doc/python.qmd) :snake:

Caution

You will see this in the terminal. This is normal, as we haven’t yet created these files.

WARN: Unable to resolve link target: doc/r.qmd
WARN: Unable to resolve link target: doc/python.qmd

5.2 _quarto.yml

This configuration file holds metadata settings.

All files within your repository will inherit these metadata settings. However, you have the flexibility to redefine these values for each individual file.

Paste the following code (you can custom title, navbar background color or both themes)

project:
  type: website

website:
  title: "Quarto tutorial"
  navbar:
    background: lightseagreen
    left:
      - href: index.qmd
        text: Home
      - text: Examples with code
        menu:
          - href: doc/r.qmd
            text: "R code"
          - href: doc/python.qmd
            text: "Python code"
    right:
      - about.qmd  

format:
  html:
    theme:
      dark: solar
      light: cosmo
    css: styles.css

Let’s have a closer look of these metadata

project type : website, let’s say it’s the default value
there is a navigation bar with a single tab
- tab name : Home
- it links to the index.qmd file ➡️ we will create it in the root
the default format is html
- with two themes : one for the dark mode (first one so it is the default theme) and one for light mode
  - on the navbar top left you will find a trigger to toggle theme from dark to light
- it use styles from styles.css ➡️ we will create it in the root

5.3 styles.css

In this file you can define all styles you can imagin.

in this file, create for example a green button

.green-button {
  display: inline-block;
  padding: 2px 5px;
  font-size: 14px;
  color: white;
  background-color: green;
  border: none;
  border-radius: 12px;
  text-align: center;
  text-decoration: none;
  cursor: pointer;
  transition: background-color 0.3s ease;
}

.green-button:hover {
  background-color: darkgreen;
}

Add a green button in the index
- [a button]{.green-button}

5.4 Create new files

Important

First of all, we will create a folder to store our files.

It’s important to work cleanly and store your files properly.

In the root, create a doc folder
In this folder, create files r.qmd and python.qmd

5.4.1 Using R Code

r.qmd

---
title: "R code"
author: "Me"
format: html
from: markdown+emoji
code-block-bg: true
code-block-border-left: "#31BAE9"
---

```{R}
alpha <- 0.5
beta <- 0.5
n_values <- 500

set.seed(123)
beta_values <- rbeta(n = n_values, shape1 = alpha, shape2 = beta)

plot(density(beta_values),
     main = expression(paste("Density of Beta(", alpha, " = 0.5, ", beta, " = 0.5) Distribution")),
     xlab = "Value",
     ylab = "Density",
     col = "blue",
     lwd = 2,
     cex.main = 1.2,
     cex.lab = 1.1,
     cex.axis = 1.0
)
```

5.4.2 Using Python Code

To run python cells, we have to install jupyter and needed packages

pip install jupyter matplotlib scipy

python.qmd

---
title: "Python code"
author: "Me"
format: html
from: markdown+emoji
code-block-bg: true
code-block-border-left: orange
---

```{python}
import numpy as np
import matplotlib.pyplot as plt
from scipy.stats import norm

x = np.linspace(-5, 5, 1000)

pdf = norm.pdf(x, 0, 1)
plt.plot(x, pdf, label='Normal Distribution')
plt.show()
```

6 Publish

We will use git to synchronise our repositories and deploy our pages on GitHub.

6.1 .gitignore

git status

You may have noticed that a _site folder has been created (during the preview). This folder contains the html pages generated from the qmd files. It should not be versioned with git.

Add _site/ in the .gitignore file

6.2 .github/workflows/publish.yml

Tip

You’ve just created a Quarto website on your computer.

Now, you want to publish it online using GitHub Pages.

To do that, imagine GitHub gives you a brand new, empty computer every time you update your site. On this empty machine, you need to:

Download your project files
Install the needed tools (Quarto, R, Python, etc.)
Install the packages your site uses
Build (render) the website
Publish it to GitHub Pages

All these steps are written in a script (called a GitHub Actions workflow), so GitHub can do them automatically every time you update your site.

Create folder .github then folder workflows
Create file publish.yml and paste the code below

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.3.0'

      - name: Install R packages from DESCRIPTION file
        uses: r-lib/actions/setup-r-dependencies@v2
        
      - name: Install Python and Dependencies
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

6.3 List R and Python Packages

As you probably know, R and Python have many packages.

Use these root files to list the packages you need

DESCRIPTION

Package: quartotuto
Type: website
Title: Quarto tuto
Description: Used to declare R dependencies
Version: 1.0
Authors@R: c(
    person("Ludovic", "DENEUVILLE",role = c("aut", "cre"), email = "ludovic.deneuville@ensai.fr"))
URL: https://ludo2ne.github.io/Quarto-tuto
License: MIT
Imports:
    dplyr,
    ggplot2,
    leaflet,
    rmarkdown
Encoding: UTF-8

requirements.txt

matplotlib
numpy
scipy

6.4 git push

Add
Commit
Push

7 Gear second

Let’s go further.

--- title: "Practical example" description: "Create a static website with Quarto" author: "Ludovic Deneuville" date: 09/20/2023 date-format: long format: html: toc: true toc-location: left toc-expand: 3 code-tools: true from: markdown+emoji number-sections: true lightbox: true --- ## Introduction{.unnumbered} You will learn how to create your first static website with Quarto. ## GitHub repository To publish our website, we will use GitHub Pages. The first step is to create a repository on GitHub. - [ ] Log in to [GitHub](https://github.com/){.external target="_blank"} - [ ] Create a new repository called `Quarto-practical` - Visibility : Public - check Add a README file - .gitignore : GitHubPages - licence : Creative Commons Zero v1.0 Universal - [ ] Create a new branch called *gh-pages* - clic on button [main]{.grey-button} - write *gh-pages* - clic on `Create branch gh-pages from main` - wait 30 seconds and then refresh the page until a *Deployments* section appears at the bottom right ::: {.callout-tip} ### Why deploy from pages branch *gh-pages* ? This will keep your branch `main` clean and avoid including html pages generated by Quarto : - branch `main` : setup and content in qmd files - branch `gh-pages` : html for deployment ::: - [ ] In the *About* section clic on :gear: - Check *Use your GitHub Pages website* - [Save changes]{.green-button} You can clic on the url. Your website is created but empty. ## Local repository We will use the IDE Visual Studio Code to edit our pages. - [ ] Login to [SSPCloud](https://datalab.sspcloud.fr){target="_blank"} - [ ] launch a service `Vscode-r-python-julia` - [ ] Open a *bash* terminal - terminal > New terminal or CTRL + ù or CTRL + SHIFT + C - [ ] Clone the repository *Quarto-practical* using `HTTPS` - [ ] Open Folder `Quarto-practical` - File > Open Folder > */home/onyxia/work/Quarto-practical* - [ ] Once again, open a *bash* terminal ::: {.callout-warning title="Licence"} The license chosen in GitHub is too permissive. Let's change it for a more restrictive one - [ ] Paste the [text of licence CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.txt){target="_blank"} in file LICENCE - BY (Attribution): Credit must be given to the creator - NC (Non Commercial): Only noncommercial uses of the work are permitted - SA (Share Alike): Adaptations must be shared under the same terms [More about Creative Commons licences](https://creativecommons.org/share-your-work/cclicenses/){target="_blank"} ::: ## Create a Quarto project Let's start by creating a quarto project. We're going to create a website project, i.e. a collection of web pages. - [ ] `quarto create project` - Type: website - Directory: . - Title: My first quarto site This command will create the following files in the current directory (`.`): - _quarto.yml: metadata - index.qmd: the home page - about.qmd: another page (not a mandatory file) - styles.css: to customize visual aspects of your Quarto website ::: {.callout-note} It is also possible to create these files manually. ::: ## Preview your site - [ ] `quarto preview` You can open the preview on a specific port. - [ ] Click on [Open in Browser]{.blue-button} ::: {.callout-tip} CTRL + C to quit the preview ::: ## Edit your files Now it's time to custom our website. ### index.qmd Let's modify the index: - adding some local metadata (between `---`) - inserting link to other pages - putting an [emoji](https://gist.github.com/rxaviers/7360908){target="_blank"} ```{.txt} --- title: "Quarto-practical" description: "Let's have fun with Quarto" author: "Me" format: html from: markdown+emoji --- ## Quarto - [External link to Quarto website](https://quarto.org/){target="_blank"} - [R example](doc/r.qmd) - [Python example](doc/python.qmd) :snake: ``` :::::: {.callout-caution} You will see this in the terminal. This is normal, as we haven't yet created these files. ``` WARN: Unable to resolve link target: doc/r.qmd WARN: Unable to resolve link target: doc/python.qmd ``` ::: ### _quarto.yml This configuration file holds metadata settings. All files within your repository will inherit these metadata settings. However, you have the flexibility to redefine these values for each individual file. - [ ] Paste the following code (you can custom title, navbar background color or both [themes](https://quarto.org/docs/output-formats/html-themes.html){target="_blank"}) ```{.yml} project: type: website website: title: "Quarto tutorial" navbar: background: lightseagreen left: - href: index.qmd text: Home - text: Examples with code menu: - href: doc/r.qmd text: "R code" - href: doc/python.qmd text: "Python code" right: - about.qmd format: html: theme: dark: solar light: cosmo css: styles.css ``` ::: {.callout-note title="Let's have a closer look of these metadata"} - project type : `website`, let's say it's the default value - there is a *navigation bar* with a single tab - tab name : Home - it links to the `index.qmd` file :arrow_right: we will create it in the root - the default format is `html` - with two themes : one for the dark mode (first one so it is the default theme) and one for light mode - on the navbar top left you will find a trigger to toggle theme from dark to light - it use styles from `styles.css` :arrow_right: we will create it in the root ::: ### styles.css In this file you can define all styles you can imagin. - [ ] in this file, create for example a green button ```{.css} .green-button { display: inline-block; padding: 2px 5px; font-size: 14px; color: white; background-color: green; border: none; border-radius: 12px; text-align: center; text-decoration: none; cursor: pointer; transition: background-color 0.3s ease; } .green-button:hover { background-color: darkgreen; } ``` - [ ] Add a green button in the index - `[a button]{.green-button}` ### Create new files ::: {.callout-important} First of all, we will create a folder to store our files. It's important to work cleanly and store your files properly. ::: - [ ] In the root, create a `doc` folder - [ ] In this folder, create files `r.qmd` and `python.qmd` #### Using R Code ````{.txt filename="r.qmd"} --- title: "R code" author: "Me" format: html from: markdown+emoji code-block-bg: true code-block-border-left: "#31BAE9" --- ```{R} alpha <- 0.5 beta <- 0.5 n_values <- 500 set.seed(123) beta_values <- rbeta(n = n_values, shape1 = alpha, shape2 = beta) plot(density(beta_values), main = expression(paste("Density of Beta(", alpha, " = 0.5, ", beta, " = 0.5) Distribution")), xlab = "Value", ylab = "Density", col = "blue", lwd = 2, cex.main = 1.2, cex.lab = 1.1, cex.axis = 1.0 ) ``` ```` #### Using Python Code To run python cells, we have to install `jupyter` and needed packages - [ ] `pip install jupyter matplotlib scipy` ````{.txt filename="python.qmd"} --- title: "Python code" author: "Me" format: html from: markdown+emoji code-block-bg: true code-block-border-left: orange --- ```{python} import numpy as np import matplotlib.pyplot as plt from scipy.stats import norm x = np.linspace(-5, 5, 1000) pdf = norm.pdf(x, 0, 1) plt.plot(x, pdf, label='Normal Distribution') plt.show() ``` ```` ## Publish We will use git to synchronise our repositories and deploy our pages on GitHub. ### .gitignore - [ ] `git status` You may have noticed that a _site folder has been created (during the preview). This folder contains the html pages generated from the qmd files. It should not be versioned with git. - [ ] Add `_site/` in the .gitignore file ### .github/workflows/publish.yml ::: {.callout-tip} You've just created a **Quarto website on your computer**. Now, you want to **publish it online using GitHub Pages**. To do that, imagine GitHub gives you a **brand new, empty computer** every time you update your site. On this empty machine, you need to: 1. **Download your project files** 2. **Install the needed tools** (Quarto, R, Python, etc.) 3. **Install the packages your site uses** 4. **Build (render) the website** 5. **Publish it to GitHub Pages** All these steps are written in a **script** (called a GitHub Actions workflow), so GitHub can do them automatically every time you update your site. ::: - [ ] Create folder `.github` then folder `workflows` - [ ] Create file *publish.yml* and paste the code below ```{.yml filename=".github/workflows/publish.yml"} on: workflow_dispatch: push: branches: main name: Quarto Publish jobs: build-deploy: runs-on: ubuntu-latest permissions: contents: write steps: - name: Check out repository uses: actions/checkout@v4 - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@v2 - name: Install R uses: r-lib/actions/setup-r@v2 with: r-version: '4.3.0' - name: Install R packages from DESCRIPTION file uses: r-lib/actions/setup-r-dependencies@v2 - name: Install Python and Dependencies uses: actions/setup-python@v4 with: python-version: '3.10' cache: 'pip' - run: pip install jupyter - run: pip install -r requirements.txt - name: Render and Publish uses: quarto-dev/quarto-actions/publish@v2 with: target: gh-pages env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` ### List R and Python Packages As you probably know, R and Python have many packages. - [ ] Use these root files to list the packages you need ```{.txt filename="DESCRIPTION"} Package: quartotuto Type: website Title: Quarto tuto Description: Used to declare R dependencies Version: 1.0 Authors@R: c( person("Ludovic", "DENEUVILLE",role = c("aut", "cre"), email = "ludovic.deneuville@ensai.fr")) URL: https://ludo2ne.github.io/Quarto-tuto License: MIT Imports: dplyr, ggplot2, leaflet, rmarkdown Encoding: UTF-8 ``` --- ```{.txt filename="requirements.txt"} matplotlib numpy scipy ``` ### git push - [ ] Add - [ ] Commit - [ ] Push ## Gear second Let's go further.