A simple MyST plugin for collecting items, optionally transforming them to add extra metadata, and then displaying them in a variety of structured views.
Out of the box, this plugin supports tables, lists, galleries, summaries, feeds, and sections.
What it looks like¶
Point {listing} at some pages and choose how to show them.
Here are the same three posts, four different ways:
:::{listing}
:path: posts/*.md
:display: table
:limit: 3
:::| Title | Date |
|---|---|
| Community roundup | June 5, 2025 |
| Your first listing | May 15, 2025 |
| Interactive widgets | April 10, 2025 |
:::{listing}
:path: posts/*.md
:display: list
:limit: 3
:::- Community roundup: Highlights from the community call — new contributors, three plugins in the works, and a roadmap for the next release cycle.
- Your first listing: A step-by-step guide to your first listing, from a bare directive to a styled gallery.
- Interactive widgets: 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.
:::{listing}
:path: posts/*.md
:display: gallery
:limit: 3
::::::{listing}
:path: posts/*.md
:display: summary
:limit: 3
:::There are six displays in all (see Displays). To install the plugin and make your first listing, see Get started.
How it works¶
Each listing goes through three stages:
Collect items from files, your table of contents, or a data file. Options:
:source:,:path:.Transform them by sorting, filtering, and limiting. By default you get the 10 newest, by their
date. Options::sort:,:filter:,:limit:.Display them as a table, list, gallery, and so on. Options:
:display:,:columns:,:tag-fields:,:label:, plus:sortable:(table),:grid-columns:(gallery), and:body-limit:(feed).
Other plugins can add their own collectors and displays (see Extending). You can’t extend the transform stage yet.
Status¶
This is an experimental plugin and its design and UX isn’t yet proven!
Jupyter Book has an issue about adding
listingfunctionality and if that results in a different MyST implementation, I’ll probably shut this project down and recommend people just use that.
But, if you want to be a bit on the bleeding edge and give feedback, that would be great!