Listings

Session 4: More Quarto for Academics

Cynthia Huang

Thursday, July 20, 2023

Make me a List!

Quarto Listings…

• generate summary ‘lists’ which display YAML metadata
• can collect metadata from multiple .qmd files or a YAML listings
• offer sorting, filtering and categorisation of list items
• have three built-in display types with customisation options
• can be placed in different locations on a page and alongside other listings

Use Cases

• event listings
• blog posts
• glossary
• team profiles
• …

Basic Listings YAML

A listing can be included on any page by adding the listing key into the YAML header:

---
title: "A page with a Listing"
listing:
  contents: # ADD items #
  type:     # PICK default / grid / table #
---

• contents controls what items appear in the listing
• type controls how the listing is displayed

More YAML, more Features!

In addition to contents and type, other listings options include:

• sort, filter
• categories
• include/exclude
• sort-ui, filter-ui
• id

See Website Reference > Listings for all options.

Listing Contents

Items for listings can be created using metadata from:

• other .qmd files in the same folder as the listing page
• a YAML file
• files across multiple folders

Listing Types

Quarto offers 3 built-in display types for listings:

• default: blog style with featured image
• grid: card style with featured image
• table: table style

See also:

• Listing Options Guide for options which modify each display type.
• Custom Listings Guide for even more customisation via EJS templates.

Listing Fields

To populate listings, Quarto uses metadata or content from targeted documents. Each listing types displays some fields by default:

Field	Default	Table	Grid
title	x	x	x
subtitle	x
author	x	x	x
description	x		x
date	x	x	x
image	x		x

Listing Fields

To display fields which are not shown by default, specify additional fields in the fields option:

listing:
  type: table
  contents: posts
  fields: [image, date, title, author, reading-time]

To modify the display name of fields, provide a mapping from the field key:

listing:
  field-display-names:
    title: "Report"

Listing Pages

Our Turn: Listings Inside a Folder

• Reopen the fresh-web website project.

• Add a listing page for contents in the folder posts/:

posts/index.qmd

---
title: "Page with Listing"
listing: default
---

• Which files show up in the listing?

Important

Don’t forget to add posts/index.qmd to your website navigation!

10:00

Listings from YAML

We can also list items from a YAML file:

people.yml

- title: "John Smith"
  email: "john.smith@example.com"
  image: images/john.jpg
- title: "Kate Jones"
  email: "kate.jones@example.com"
  image: images/kate.jpg

Just like with navbar items, listing items must be properly indented

Listings from Multiple Sources

We can created a listing from multiple sources of metadata:

writings.qmd

title: "Writings"
listing:
  contents:         # e.g.
    - posts         # .qmd files
    - articles      # in posts/ and articles/
    - old-posts.yml # AND items from other websites

Listing Location

To specify the position of a listing use the id option:

---
title: "Listing Example"
listing:
  id: sample-listings
  contents: posts
  sort: "date desc"
  type: table
---

You can review the following documents for additional information:

::: {#sample-listings}
:::

Learn more about Quarto [here](https://www.quarto.com).

Your Turn: YAML Listings

• Add a yaml file with at least 3 items (e.g. people.yml or definitions.yml)
• Include title, description and one custom field (e.g. email or definition)
• Add a listing on the home page of the website index.qmd with a suitable type.
• Stretch: Change the location of the listing with the id option

15:00

Listing Tools

Categories

The categories feature allows website users to filter items.

When a user presses a category on the right, the listing will update to show only items which match that category.

Categories

1. Turn on categories in your listing:

listings:
  type: default
  categories: true

2. Adding category values to each item or document listed:

- title: "Kate Jones"
  email: kate.jones@example.com
  categories: 
    - alumni

Sorting

By default, items will be sorted by title. To modify this use the sort option.

listing:
  contents: posts
  sort:
    - "date"
    - "title desc"

This listing sorts items first by date in ascending order then by descending title

Interactive UI

By default, users can:

• sort by title, date and author
• filter/search all metadata fields

We can disable these features or limit the fields they apply to:

listing:
  sort-ui: false     # no sorting
  filter-ui: [title] # only search the title field

useful for defintion glossary

Your Turn: Listing Tools

Continue with the YAML listing you created before.

• Add categories to each item
• Turn on categories in your listing
• Modify the sort-ui and/or filter-ui

10:00