Create a static site

Build a static site using Quarto in just 10 minutes

General principle

With Quarto, it’s very easy to create a static site containing HTML pages, slides, executed Python or R code, notebooks, pdf files…

It only takes 10 minutes to get a first result, perhaps a little more the first time.

• You define Quarto setup
• You write your content in .qmd files with markdown language
• Quarto will generate the site’s html pages from these .qmd files

1 Local use

You will need the following tools to work locally :

• Install Quarto
• Choose an editor and install it, for example Visual Studio Code or R Studio (also created by Posit)
• Optionnal: if you want to generate pdf files, install tinytex quarto install tinytex

1.1 Create a Quarto project

You can read official documentation or simply follow these advices

To create a Quarto projet you will need the following files :

File	Description
_quarto.yml	Project Metadata
index.qmd	Home page
styles.css	CSS file for styling the project

Tip

We strongly advice you to also create a folder named doc to store your content in a clear tree structure.

Example of trees:

Simple

├── index.qmd
├── _quarto.yml
├── styles.css
└── doc/
    ├── page1.qmd
    ├── page2.qmd
    └── page3.qmd

Advanced

├── index.qmd
├── _quarto.yml
├── styles.css
├── doc/
|   ├── lesson/
|   │   ├── img/
|   │   │   ├── image1.jpg
|   │   │   └── image2.jpg
|   │   ├── lesson1.qmd
|   │   └── lesson2.qmd
|   ├── practical/
|   │   └── practical1.qmd
|   └── presentation/
|       └── presentation1.qmd
├── .gitignore
└── .github/
    └── workflows/
        └── publish.yml

• Create a folder with files of the simple tree

1.2 Metadata

• Create at the project root, a file named _quarto.yml

Simple

project:
  type: website
website:
  title: "My website title"
  navbar:
    background: "#447099"
    left:
      - href: index.qmd
        text: Home
      - text: "Drop-down list of pages"
        menu:
          - href: doc/page1.qmd
            text: "Page 1"
          - href: doc/page2.qmd
            text: "Page 2"
      - href: doc/page3.qmd
        text: "Direct link to Page 3"
    right:      
      - icon: github
        href: "https://github.com/<username>/<repository_name>"
        target: "_blank"
format:
  html:
    theme:
      dark: solar
      light: cosmo
    css: styles.css

Advanced

_quarto.yml file of Quarto-tuto.

1.3 Create your index

• At the project root, create file index.qmd
  • It will contain some metadata (title, description, author…) and then your content in markdown language

---
title: "My home page"
description: "Description of my home page"
author: "Ludovic Deneuville"
format: html
from: markdown+emoji
---

## My content

my content using Markdown language

1.4 Create pages

• The same way you created the index file, create files doc/pages1.qmd, doc/pages2.qmd, doc/pages3.qmd

Tip

If you want more markdown content, feel free to see code of files in the Examples section, such as Practical

1.5 Play with styles

• At the project root, create file styles.css
  • you can let it empty for now

1.6 Render

• In a terminal, run quarto render. This command will convert your qmd files to html
• Go to folder _site and open your index.html

Congratulation

🎉 you created your first quarto website!

2 Deploy with GitHub pages

2.1 Create a repository

• Log in to GitHub
• Create a new repository
• Create a new branch named gh-pages

2.2 Clone your repository

• Paste in your local repository the content of your quarto project

• At the root, add a .gitignore file to exlude these folders

  /.quarto/
  /_site/ 

• Add this file to setup a publish pipeline

  ├── .github/
  │   └── workflows/
  │       └── publish.yml

• Paste this content

  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: Render and Publish
          uses: quarto-dev/quarto-actions/publish@v2
          with:
            target: gh-pages
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note

The .github/workflows/publish.yml file contains the list of actions required to deploy the site.

Example of Quarto-tuto

• Using Git, add, commit files and then push
  • A github pipeline is triggered by a push
• In your GitHub repository, check in the Action section if everything is fine

A few minutes later, the site will be available on https://<username>.github.io/<repository_name>

• On the project’s GitHub page, add this link in the About section

3 Python Setup

Note

If you want to execute Python code in your qmd files.

3.1 Local

• Install Python
• Install Jupyter : pip install jupyter
• List needed packages in file requirements.txt at the project root
• pip install -r requirements.txt

3.2 Remote

• In file .github/workflow/publish.yml, add this step before Render and Publish

      - 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

4 R Setup

Note

If you want to execute R code in your qmd files.

4.1 Local

• Install R
• Install needed packages

4.2 Remote

• List needed packages in file DESCRIPTION at the project root

• In file .github/workflow/publish.yml, add this step before Render and Publish

      - 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