Creating a Portfolio with Quarto

Showing off your cartographic and scientific work doesn’t need to be hard.

Housekeeping

If you’re just watching, or reading this later:

  1. Download and install Quarto
  2. Download and install an IDE like VSCode

Quarto

What is it?

An open-source scientific and technical publishing system

  • Write your content in simple text files
  • Render to dozens of possible formats, even multiple at once
  • Lots, lots more

Quarto is for…

Students and Academics?

  • Tables of contents / figures
  • Cross-references
  • Bibliographies
  • Footnotes
  • Computations and formulas

Quarto is for…

Professionals?

  • Showcase maps, apps, images
  • Create interactive infographics
  • Make a simple, easy-to-manage website
  • Create slide decks (like this one!)

Quarto is for…

Developers?

  • Share code and show its output
  • Easy code copy and syntax highlighting
  • Dynamically rendered content

Creating a Website

quarto create

  1. quarto create
  2. Create: project
  3. Type: website
  4. Directory: .
  5. Title: My Portfolio

_quarto.yml

This is the master config file. Changes here will apply to the entire site.

project:
  type: website

website:
  title: "My Portfolio"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true

Preview the site

quarto preview

flowchart LR

1[_quarto.yml]
2[.qmd files]

subgraph 3[the _site directory]
4[.html files]
5[all the css and js stuff]
end

1 & 2 --> 3

You can leave the preview terminal running. As you make changes to the files in your project, it will automatically refresh the page.

QMD Files

What are they?

  • QMD → Quarto Markdown. It’s just text!
  • Every .qmd file = 1 website page
  • QMD folder structure = website structure

All formatting, images, layout options, etc., are simply part of the text.

Read Quarto’s Authoring guide for all the details.

Portfolio Content

If you’re following along: all portfolio content is available in the Quarto Portfolio Workshop code repo!

You can use those files to create a sample portfolio, or swap in files of your own.

Let’s make a new page!

  1. Create a new folder, portfolio
  2. Create another folder within that, lithuania
  3. Create the file index.qmd in that folder

Front Matter

“Front matter” is a small section of YML at the top of a markdown document that provides metadata.

At the very beginning of the new file, add the following details:

---
title: "Vialikaje Kniastva Litoŭskaje"
date: "1607"
---

Page Content

Below that, you can enter whatever other details you wish, following markdown conventions.

Don’t forget your map!

![](./lithuania.jpg)

# Additional Details

Part of the Atlas Minor

Let’s do one more

Create another folder in the portfolio directory, with an index.qmd in it.

Call it world. Paste the following:

---
title: Nova et Aucta Orbis Terrae Descriptio ad Usum Navigantium Emendate Accommodata
subtitle: New and more complete representation of the terrestrial globe properly adapted for use in navigation
date: "1569-08"
description: Originally printed across 18 sheets, presented here as a single composite image.
---

# The Map

:::{.column-page}
![](world.jpg)
:::

About Page: about.qmd

Generated automatically by Quarto, but there’s not much here.

For a portfolio, let’s put a little bio in here.

My name is Gerardus Mercator. You may know me for my widely (and unjustly!) hated map projection, but I did a lot more than exaggerate the poles!

# Education

## 's-Hertogenbosch: *1526—1530*

Studied Bible, Latin, logic, rhetoric.

## University of Leuven: *1530—1532*

Graduated Magister in 1532

# Acheivments and Experience

- Apprenticed to Gaspar van der Heyden
- Engraved terrestrial globe of Gemma and Gaspar Van der Heyden (1536)
- Produced many award-winning globes and maps
- Developed theory of magnetism

# Fun Facts

I really did wear that funny hat! It was quite the fashion at the time.

I coined the term "atlas"!

Built-in About Themes

In the front matter, include the item about with the following details:

Quarto will render the page using a special template!

---
title: "About"
about:
  template: trestles
  image: mercator.jpg
  links:
    - icon: wikipedia
      text: Wikipedia
      href: https://en.wikipedia.org/wiki/Gerardus_Mercator
toc: false
---

Listings

What’s a listing?

  • Automatically populated list / table / grid of pages
  • Options for sort, filter, and search
  • Displays information from post metadata

The Home Page: index.qmd

Let’s replace the placeholder text of the root-level index.qmd with a listing.

In the front matter:

---
title: "My Portfolio"
listing: default
---

Listing Options

  • type, to change to a grid or table
  • fields, to customize metadata fields shown
  • field-display-names and date-format to change appearance
  • contents, to only list specific files / folders
  • sort-ui, to let users sort your listing
  • filter-ui, to let users search / filter your listing

And more!

A more customized listing

---
title: "My Portfolio"
listing:
  contents: portfolio
  type: default
  sort: "date"
  fields: 
    - title
    - date
    - description
    - image
  field-display-names:
    date: "Year"
  date-format: "YYYY"
  filter-ui: true
  categories: true
---

Site Config

Revisiting _quarto.yml

  • location and contents of navbar
  • headers and footers
  • color theme(s)
  • all kinds of other options

Site Theme

Add these lines to the format/html section of the config:

  format:
    html:
      theme:
        light: litera
        dark: vapor

Other Things to Check Out

  • favicon
  • search settings
  • custom 404 page

Publishing

Render Files

  1. quarto render
  2. Rendered website files go into _site directory
  3. Copy _site directory to root directory of web host
  4. You have a website!

Prerequisites: web host and domain

quarto publish

Quarto can publish directly to the web!

Important

You may need to change the output-dir setting to a platform-specific name, depending on the destination.

  • GitHub Pages
  • Posit Connect
  • Netlify
  • Confluence

Code Blocks

Writing Code

Surround your text with ``` and an optional language designator to render your code!

Includes syntax highlighting, copy button, line numbers, and annotations.

Figure 1: The code, as written in my QMD file

Rendered:

from random import random

def isThisCool():
  if random() > 0.5:
    return 'It is cool.'
  else:
    return 'It is not cool.'
1
Lacking other criteria, we flip a coin.

Executable Code

Put curly braces around the language. Quarto will execute your code during document rendering!

```{python}
from random import random
import datetime as dt

def isThisCool():
  if random() > 0.5:
    return 'It is cool.'
  else:
    return 'It is not cool.'

print(f'Slides rendered at {dt.date.today().strftime("%A, %B %d %Y")}.')
print(isThisCool())
```
1
Putting my slides together at the last minute, as usual.
2
Flip the coin: is this cool? 
Slides rendered at Sunday, October 18 2026.
It is not cool.

More executable code!

```{python}
from ipyleaflet import Map, Marker

center = (40.7, -89.6)
m = Map(center=center, zoom=10)

marker = Marker(location=center, draggable=True)
m.add(marker)

display(m)
```

More executable code!

Code comes from MatPlotLib examples.1

Code 
```{python}
#| code-fold: true
#| fig-cap: A random scatter plot
#| fig-alt: A scatter plot of dots in varying sizes and shades of blue

import matplotlib.pyplot as plt
import numpy as np

plt.style.use('_mpl-gallery')

# make the data
np.random.seed(3)
x = 4 + np.random.normal(0, 2, 24)
y = 4 + np.random.normal(0, 2, len(x))
# size and color:
sizes = np.random.uniform(15, 80, len(x))
colors = np.random.uniform(15, 80, len(x))

# plot
fig, ax = plt.subplots()

ax.scatter(x, y, s=sizes, c=colors, vmin=0, vmax=100)

ax.set(xlim=(0, 8), xticks=np.arange(1, 8),
       ylim=(0, 8), yticks=np.arange(1, 8))

plt.show()
```

A scatter plot of dots in varying sizes and shades of blue

A random scatter plot

Code: Use cases, please

  • Sharing computational code and its output
    • Python and / or R
  • Sharing interactive web maps
    • leaflet
    • maplibre
    • esri tools
  • Creating fancy plots and infographics of your research data
    • matplotlib
    • plotly (interactive!)

A few other things

There’s way too much to cover in one workshop. But here’s a quick sampler:

Scholarly Stuff

  • built-in support for bibliography files
  • footnotes1
  • cross-references: here’s one to Figure 1
  • appendices

Other Tools

  • simultaneously render to PDF, Jupyter Notebook, and more
  • an entire Dashboards capability we didn’t even touch
  • presentations (like this one, right now)

Some real examples

Questions?

Be in Touch!

josh@jcarlson.page

https://jcarlson.page

@jcarlson@mapstodon.space