Basics

Getting Started With Quarto

Hamel Husain

Parlance Labs

Create a new project (website)

Create a new GitHub repo and clone it locally

gh repo create my-quarto-website --clone --public

Initialize the quarto project

quarto create project

or

quarto create project website mysite

See creating a website

Preview Site

quarto preview

Now, try to change some contents and see what happens.

The _site folder contains the html files that are generated.
You can serve this site with any web server.

For example, with Python:

python -m http.server --d _site

Your site will be served at localhost:8000

Look at the help!

When starting out, its helpful to look at the help for every command.

quarto preview --help

Debugging Tips

1. Preview a single document quarto preview somefile.qmd
2. --log-level error can help you focus on what is important
3. Delete the _site folder

Tips for starting out

1. Do not create a new site from scratch

2. Find a website you like, and start editing it. It’s easiest to learn by example.

3. One of the best examples is the source code for the official Quarto docs, since they demonstrate all of the features of Quarto!

Learn to navigate the Quarto docs website.

This site was created from this repo.

Navigating Quarto Docs

_quarto.yml

project:
  type: website

website:
  title: "Quarto for Python devs"
  description: "Posit::Conf 2023"
  ...

format:
  html:
    ...
  revealjs: 
    ...

Start with the reference page page, where you will see:

• Projects (website, book etc.)

• Formats (html, revealjs, pdf, etc..)

Tip

Many formats have the same options and are repeated in the docs.

Also see the project guide

Using VSCode

• When authoring _quarto.yml or .qmd files, its best to use VSCode with the Quarto extension.

• Demo this by opening the source code.

• Code blocks

a = 10
b = 20

c = a + b

import pandas as pd
pd.DataFrame({'col': [a,b,c]})

My Other favorite features:

• Front matter completion
• _quarto.yml
• relative links

And much more!

Using Notebooks

JupyterLab extension.

• Renders Quarto elements like Callouts, Divs, Mermaid, Front matter, etc.
• The VSCode plugin is more fully featured. Use this if you prefer JupyterLab.
• Still get code block contextual help.

Recommendation: Use VSCode Notebooks if possible (you also get CoPilot there).

Exercise

1. Create a new Quarto website and preview it locally.
2. Edit the _quarto.yml file to change the title of the website.
3. Edit the _quarto.yml file to change the theme of the website.
4. Author a new .qmd file and preview it locally.
5. Author a page as a Jupyter Notebook and preview it locally.
6. Hide the code output of a code block.
7. Enable table of contents for a page.
8. Clone the repo for this tutorial and add a navbar.