Get started

Reference the released plugin bundle directly from GitHub in your myst.yml. This pulls the bundle attached to the latest release, so MyST loads it without a build or install step:

project:
  plugins:
    - https://github.com/myst-contrib/myst-listing/releases/latest/download/plugin.mjs

To pin a specific version, swap latest/download for a tag, e.g. download/v0.1.0.

Alternatively, clone this repository, build the bundle with bun run build (it ends up in dist/plugin.mjs), and reference it from a local path:

project:
  plugins:
    - path/to/plugin.mjs

Then collect a folder of pages and display them. This shows the pages in posts/ as a table, newest first. By default a listing shows at most 10 items.

```{listing}
:path: posts/*.md
:columns: title,date
```

Here’s what that looks like:

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

Each page’s title comes from its title frontmatter, or its first heading if there isn’t one. Give each page a date in its frontmatter so the newest ones come first.

Next steps¶

• For a walkthrough of the main sources and displays, follow the Tutorial.

• To show cards, bullets, or full posts, pick a display.

• To sort, filter, or limit items, see Transform.

• To list the pages in one section of your site, use the toc source.

• To make a listing from a YAML, JSON, or TOML file, see Collectors.

• To reuse a listing on another page, give it a label.