article-list

Renders a sorted list of articles from a content directory.

::article-list queries a content directory at build time and renders its articles as a linked list. Articles with an order frontmatter field are shown first, sorted ascending by order; remaining articles are sorted by publish-date descending, with undated articles last. See Frontmatter for the full sort rule.

index.mdx handling — index.mdx at the root of the queried directory is always excluded: it is the section page for that directory, not a peer article. A subdirectory's index.mdx (e.g. subdir/index.mdx) is always treated as a peer and appears at the subdirectory's slug (subdir), regardless of whether recursive is set. The recursive flag only controls whether the contents inside subdirectories are also collected.

Maps to the <ArticleList /> React component via the kebab-case → PascalCase directive convention.

Reference

::article-list{dir=guides}  
::article-list{dir=guides recursive limit=5}

Attribute	Type	Required	Default	Description
`dir`	`string`	Yes	—	Directory path relative to `content/`.
`recursive`	`boolean`	No	`false`	When `true`, collects articles from all nested subdirectories.
`limit`	`number`	No	—	Maximum number of articles to show.

Examples

All articles in a directory

::article-list{dir=directives/article-list}

With a limit

::article-list{dir=directives/article-list limit=1}

directives/article-list/blog-index
Building a Blog Index
Turn a folder of dated posts into an automatically sorted listing.
Jul 22, 2026Read

Recursive — include subdirectories

::article-list{dir=directives/article-list recursive}