DocCardList

The DocCardList component renders a responsive grid of cards that link to other documentation pages. Use it on category index pages to give readers an overview of available topics, or anywhere you want a visual navigation block.

This is the Trellis Docs equivalent of Docusaurus' <DocCardList />.

Features

• Auto mode — pass a category name and cards are generated from the sidebar config + doc frontmatter
• Manual mode — pass an explicit items array for full control
• Responsive 2-column grid (1 column on mobile)
• Styled with design tokens — adapts to light and dark mode

Usage

Auto mode (from sidebar)

Pass the category prop with the exact sidebar category label. The component finds the matching category in config/sidebar.ts and renders a card for each child item, pulling titles and descriptions from frontmatter.

<DocCardList category="Guides" />

Result:

Grouped mode (nested subcategories)

When a sidebar category has subcategories, passing grouped renders each subcategory as its own titled section with its own card grid. Direct docs of the top-level category render first in an ungrouped block; subcategories then render in sidebar order beneath them.

<DocCardList category="Contribute to Alchemy" grouped />

Flat mode (the default) collapses subcategories into single cards linking to each subcategory's index page. Grouped mode expands them into sections, which is what you want on overview pages where subcategories have multiple children the reader might want to skim.

One level of grouping only — sub-subcategories still collapse to single cards within their parent section.

Manual mode (explicit items)

Pass an items array when you want full control over which cards appear and in what order.

<DocCardList items={[
  {
    title: "Getting Started",
    description: "Install Trellis and create your first project.",
    href: "/getting-started/"
  },
  {
    title: "Content Authoring",
    description: "Create new pages, blog posts, and release notes.",
    href: "/guides/docs/"
  }
]} />

Result:

Single card

Use DocCard directly when you need just one card.

<DocCard
  title="Deployment"
  description="Deploy your Trellis site to any static host."
  href="/guides/deployment/"
/>

Props

DocCardList

Provide either category or items. If both are passed, items wins.

DocCardListItem

DocCard

Tips

• Category names are case-insensitive — "guides", "Guides", and "GUIDES" all match the same sidebar category.
• Descriptions come from frontmatter — in auto mode, each card's description is pulled from the description field in the target page's YAML frontmatter. Pages without a description show only the title.
• Nested categories — the category prop searches the full sidebar tree, so nested categories work too.
• Both components are globally registered — no import needed in MDX files.

1. Do something first.

   Tips

   • You can also resize the widget if it's too wide by using the resize blue handle in the bottom-right corner of the widget.

     

   • In addition to adding widgets, you can Delete widgets.

     

   • In addition to adding widgets, you can Restore Defaults or Clear All widgets.

     

2. Do something else.