Displays
A {listing} renders its collected items with one of three built-in displays, chosen with the :display: option.
Each leads with a different field: galleries are image-forward, summaries are text-forward.
Below is a quick tour of each; follow the links for the full options.
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. Each card leads with its thumbnail.
:::{listing}
:source: yaml
:path: links.yml
:display: gallery
:::summary¶
Stacked cards that foreground the full description.
:::{listing}
:path: posts/*.md
:display: summary
:::Highlights from the community call — new contributors, three plugins in the works, and a roadmap for the next release cycle.
A step-by-step guide to your first listing, from a bare directive to a styled gallery.
Interactive widgets have landed. Embed live, manipulable figures directly in your pages — sliders, toggles, and plots that respond to readers — without writing a single line of JavaScript yourself.
The Zebra release is out — faster builds, a redesigned gallery, and a long list of bug fixes contributed by the community.
What happened in February — a roundup of fixes, docs improvements, and the first community contributions to land.
The very first post — what this project is, why we started it, and where we hope to take it over the coming year.
A look back at the very first prototype — what worked, what didn't, and the rough edges we sanded down before the public launch.
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 |