Displays
A {listing} renders its collected items with one of five built-in displays, chosen with the :display: option.
Each leads with a different field:
Display | Best for | Leads with |
|---|---|---|
dense, scannable lists | the columns you pick | |
visual collections | a thumbnail image | |
blog indexes, reading lists (scan and click through) | the description | |
blogs, bios (read in place) | the full body | |
pages that are the listing: release notes or combined meeting notes | an |
Below is a quick tour of each; follow the links for the full options. Sorting, filtering, and limiting work the same in every display and are covered in Transform.
table¶
The default. Pick the columns you want with :columns:.
:::{listing}
:path: ../posts/*.md
:columns: title,date
:::| Title | Date |
|---|---|
| Community roundup | June 5, 2025 |
| Your first listing | May 15, 2025 |
| Interactive widgets | April 10, 2025 |
| Zebra release notes | March 1, 2025 |
| A February update | February 1, 2025 |
| Hello world | January 1, 2025 |
| The first prototype | November 20, 2024 |
gallery¶
An image-forward card grid.
:::{listing}
:source: yaml
:path: ../links.yml
:display: gallery
:::summary¶
Stacked cards that show each item’s description.
:::{listing}
:path: ../posts/*.md
:display: summary
:::feed¶
The full body of each item, stacked for reading straight down.
:::{listing}
:path: ../posts/*.md
:display: feed
:body-limit: 2
:limit: 3
:::Our latest community call was the busiest one yet. Here are the highlights from a packed hour of demos and discussion.
Five new contributors landed their first pull requests this month.
Three plugins are in the works, including a GitHub-releases collector.
We sketched a roadmap for the next release cycle, with a focus on accessibility.
Start here if you’re new.
Interactive widgets let you embed live, manipulable figures directly in your pages. Readers can drag a slider or toggle a series and watch the figure respond, with no JavaScript on your part.
Widgets work anywhere a figure does, including inside grids. They fall back to a static image when scripting is unavailable.
sections¶
Like feed, but each item is a real ##-level section that appears in the page outline.
:::{listing}
:path: ../posts/*.md
:filter: tags=release
:display: sections
:limit: 2
:::Interactive widgets¶
Interactive widgets let you embed live, manipulable figures directly in your pages. Readers can drag a slider or toggle a series and watch the figure respond, with no JavaScript on your part.
Widgets work anywhere a figure does, including inside grids. They fall back to a static image when scripting is unavailable.
Zebra release notes¶
Zebra is our biggest release yet, focused on build speed and the gallery display. Upgrade with your usual package manager; no configuration changes are required.
A redesigned gallery with responsive columns and even card heights.
Per-field tag colors, so you can show more than one kind of tag at a glance.
A redundant re-parse that slowed large projects; builds are roughly twice as fast.
Thumbnails with transparent backgrounds now stay legible in dark themes.
Several smaller layout glitches on narrow screens.
Graceful degradation for unknown configuration¶
An unknown :source: warns and renders a note:
:::{listing}
:source: nope
:::An unknown :display: warns and falls back to a table:
:::{listing}
:path: ../posts/*.md
:display: nope
:::| Title | Date |
|---|---|
| Community roundup | June 5, 2025 |
| Your first listing | May 15, 2025 |
| Interactive widgets | April 10, 2025 |
| Zebra release notes | March 1, 2025 |
| A February update | February 1, 2025 |
| Hello world | January 1, 2025 |
| The first prototype | November 20, 2024 |