Displays

A {listing} renders its collected items with one of six built-in displays, chosen with the :display: option. Each leads with something different:

Sorting, filtering, and limiting work the same in every display and are covered in Transform.

Options for every display¶

Each display page covers its own options. These work across displays.

Color-code several tag fields¶

By default the tag row shows each item’s tags. List several fields with :tag-fields: to show more than one kind of tag, each in its own color. In an item, each of these fields can hold a list or a comma-separated string:

:::{listing}
:source: yaml
:path: ../links.yml
:display: gallery
:tag-fields: libraries, domains
:::

Colors come from a small fixed palette, assigned by list order, so keep the order consistent across pages. It works in every display that shows tags: gallery, summary, feed, and sections.

Filter it live¶

Add the searchfilter plugin to your myst.yml to give readers a search box that filters a listing as they type:

project:
  plugins:
    - https://raw.githubusercontent.com/jupyter-book/myst-plugins/main/plugins/searchfilter/searchfilter.mjs

Then put a {searchfilter} directive on the page, with the item selector for your display as its argument. Each display page has a demo.

Labels and embeds¶

A :label: makes a listing a reference target. Link to it, or embed it on any page in your project with ![](#label). The embed shows the same items as the original. Its :path: resolves from the page that holds the {listing}, not the page that embeds it:

:::{listing}
:label: recent-posts
:path: ../posts/*.md
:columns: title,date
:::

![](#recent-posts)

Unknown displays¶

An unknown :display: warns and falls back to a table:

:::{listing}
:path: ../posts/*.md
:display: nope
:::