Collectors

Before a {listing} can display anything, it has to collect its items. The :source: option picks a collector, which produces a list of items (defined below). These collectors are built in, and other plugins can add more (see Extending):

A relative :path: resolves from the page containing the directive, like a Markdown link.

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:

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.

toc¶

Set :source: toc to list the pages nested under a page in your myst.yml table of contents, in the same order. By default it lists the children of the page holding the listing; point :path: at another page to list its children instead. Pair it with the list display for a table of contents that shows each page’s description:

:::{listing}
:source: toc
:path: displays/index.md
:display: list
:::

Each item is the page’s frontmatter, so :columns: can show any field it has. The first column is the link text, so short_title gives shorter links (pages without one fall back to title):

:::{listing}
:source: toc
:path: displays/index.md
:display: list
:columns: short_title,description
:::

The first page in the toc is the site’s root page, so its children are the other top-level entries. This lists the top level of this site from any page:

:::{listing}
:source: toc
:path: index.md
:display: list
:::

Items come in toc order, so they aren’t sorted or limited unless you set :sort: or :limit:. A few things to know:

• Only direct children are listed, not grandchildren.

• A url entry becomes an external link, and a title with no file becomes an unlinked item.

• hidden entries are skipped.

• A notebook’s fields come from the frontmatter in its first cell.

• Your myst.yml needs an explicit toc; extends: and _toc.yml aren’t read.

• file entries need their extension (guides/intro.md, not guides/intro), as mystmd itself recommends.

yaml¶

Set :source: yaml and point :path: at a .yml file whose top-level entries use the item fields:

:::{listing}
:source: yaml
:path: links.yml
:columns: title,description,date
:::

For a short, one-off listing, write the YAML list in the directive body instead. The body wins over :path: when both are given.

:::{listing}
:source: yaml
:columns: title,description
- title: Inline One
  description: Written in the directive body
- title: Inline Two
  description: No file needed
:::

json¶

Like yaml, but for JSON: point :path: at a .json file holding one top-level array, or write the array inline in the directive body.

JSON is most useful when another tool writes the data for you. For example, gh can dump GitHub issues into a listing-ready file:

gh issue list --limit 5 --json title,url,updatedAt > issues.json

This site’s issues.json came from that command, so the table below shows this repo’s open issues:

:::{listing}
:source: json
:path: issues.json
:columns: title,updatedAt
:sort: updatedAt-desc
:::

toml¶

Like yaml, but for TOML. TOML has no top-level list, so wrap the items in a single array-of-tables. The key’s name is up to you; here it’s items:

:::{listing}
:source: toml
:columns: title,description
[[items]]
title = "Toml One"
description = "Written in the directive body"

[[items]]
title = "Toml Two"
description = "No file needed"
:::

A .toml file works the same way:

:::{listing}
:source: toml
:path: links.toml
:columns: title,description,date
:::

csv and tsv¶

Set :source: csv and point :path: at a .csv file. The header row names the item fields, and each row after it is one item. Separate several tags in one cell with ;:

:::{listing}
:source: csv
:path: links.csv
:columns: title,description,tags
:::

Like the other data sources, you can write the CSV in the directive body instead:

:::{listing}
:source: csv
:columns: title,description
title,description
Csv One,Written in the directive body
Csv Two,"Quoted, so it can hold a comma"
:::

Every value is a string, so a numeric column sorts as text.

For a tab-separated file, use :source: tsv:

:::{listing}
:source: tsv
:path: links.tsv
:columns: title,description
:::

Unknown sources¶

An unknown :source: warns and renders a note:

:::{listing}
:source: nope
:::