Collectors
Before a {listing} can display anything, it has to collect its items.
A collector turns the :source: option into a list of items (defined below).
The plugin ships with two built-in collectors.
Authors choose which one with :source:.
Source | Collects from |
|
|---|---|---|
| Markdown files on disk, using their frontmatter | a glob, e.g. |
| A YAML file whose top-level entries are items | a |
Items¶
An item is a plain object: a collector produces a list of them, and a display renders them. No field is required, but the built-in displays and options understand these:
Field | Used for |
|---|---|
| The item’s name. Shown as the heading, linked to |
| Where the title and gallery cards link to. |
| Summary text. Shown in full by |
| Sorted on by the default |
| A single name or a list. Shown in the |
| A list of strings. Shown as pills; |
| Image URL. Leads each |
Any other fields pass through untouched; use them as :columns: or :filter: targets.
files¶
The default. Point :path: at a glob of Markdown files; each file’s frontmatter becomes an item, and its URL links to the built page.
Most examples in the displays pages use this source - for instance the summary page collects posts/*.md.
yaml¶
Set :source: yaml and point :path: at a .yml file whose top-level entries already use the item fields.
The table and gallery pages both show this in action, collecting from links.yml.
Add new collectors¶
Collectors are designed to be extendable with other MyST plugins. See Extending from another plugin.