## Overview

`CategoryList` shows the first few documents of one category, then links to the whole category. A blog is the typical use: show the three newest posts on the homepage and let readers continue to the archive. Numbered note trays and ordinary nested categories work the same way.

Two layouts render exactly the same items and metadata:

- **`cards`** (the default): equal bordered cards, one column on a narrow component, two from 36rem and three from 64rem of component width. Never more than three.
- **`list`**: a quiet two-column index of rows with separators, which becomes one column at a component width of 520px or less. Rows read left to right, then down (1, 2 / 3, 4), in both the page source and keyboard order.

The columns follow the width of the component itself, not the window, so a list placed in a narrow column collapses even on a wide screen.

**Info**

`CategoryList` is globally available in MDX doc pages, with no import needed. The current locale and version are injected automatically. It renders no heading of its own: place it under a `##` heading. Item titles are `h3` elements; under a `###` heading, pass `titleLevel={4}`.



## Live examples

### Blog as cards

The Blog category is a dated note tray, so each card leads with its publication date.

- [Moving a Showcase Off Astro](https://zudo-doc.takazudomodular.com/docs/blog/migrating-from-astro/) (2026-03-27): A framework migration is easier to review when the content tree remains the stable center of the site.
- [Warn First, Error Later](https://zudo-doc.takazudomodular.com/docs/blog/tag-governance-warn-first/) (2026-03-10): Tag governance can start as a useful audit signal before it becomes a build gate.
- [Keeping Doc History Out of the Build](https://zudo-doc.takazudomodular.com/docs/blog/non-blocking-doc-history/) (2026-02-24): Git history stays useful when expensive per-document work runs outside the main site build.
- [Blog](https://zudo-doc.takazudomodular.com/docs/blog/)

```mdx
<CategoryList category="blog" limit={3} showTags showCount />
```

### Blog as a list

- [Moving a Showcase Off Astro](https://zudo-doc.takazudomodular.com/docs/blog/migrating-from-astro/) (2026-03-27): A framework migration is easier to review when the content tree remains the stable center of the site.
- [Warn First, Error Later](https://zudo-doc.takazudomodular.com/docs/blog/tag-governance-warn-first/) (2026-03-10): Tag governance can start as a useful audit signal before it becomes a build gate.
- [Keeping Doc History Out of the Build](https://zudo-doc.takazudomodular.com/docs/blog/non-blocking-doc-history/) (2026-02-24): Git history stays useful when expensive per-document work runs outside the main site build.
- [Designing the 16rem Drawer](https://zudo-doc.takazudomodular.com/docs/blog/sixteen-rem-drawer/) (2026-02-11): A fixed-width sidebar drawer keeps navigation predictable without taking over the document.
- [Blog](https://zudo-doc.takazudomodular.com/docs/blog/)

```mdx
<CategoryList category="blog" limit={4} layout="list" />
```

### Numbered notes

Getting Started is an undated note tray. Its items lead with their category number, taken from the whole tray, so an excerpt keeps the same numbers the sidebar shows.

- [01. Introduction](https://zudo-doc.takazudomodular.com/docs/getting-started/introduction/): Learn what zudo-doc is, its features, and how it works.
- [02. Installation](https://zudo-doc.takazudomodular.com/docs/getting-started/installation/): How to install and set up zudo-doc for local development.
- [03. Setup Preset Generator](https://zudo-doc.takazudomodular.com/docs/getting-started/setup-preset-generator/): Interactive helper to generate setup presets for create-zudo-doc.
- [04. Writing Docs](https://zudo-doc.takazudomodular.com/docs/getting-started/writing-docs/): How to create and organize documentation pages in zudo-doc.
- [Getting Started](https://zudo-doc.takazudomodular.com/docs/getting-started/)

```mdx
<CategoryList category="getting-started" limit={4} layout="list" />
```

### An ordinary category

An ordinary category has no numbers or dates in the leading slot. By default it lists every document page below it; `scope="direct"` keeps only its direct children.

- [Configuration](https://zudo-doc.takazudomodular.com/docs/guides/configuration/): The single zudoDoc() config reference — every field and its default.
- [Custom Components](https://zudo-doc.takazudomodular.com/docs/guides/custom-components/): Add presentational MDX components, overrides, and experimental interactive islands.
- [Frontmatter](https://zudo-doc.takazudomodular.com/docs/guides/frontmatter/): Complete reference for all available frontmatter fields in zudo-doc documents.
- [Sidebar](https://zudo-doc.takazudomodular.com/docs/guides/sidebar/): How the sidebar navigation is structured and configured.
- [Note Trays](https://zudo-doc.takazudomodular.com/docs/guides/note-tray/): Build flat, ordered categories for notes, journals, and other sequential writing.
- [Editorial Navigation](https://zudo-doc.takazudomodular.com/docs/guides/editorial-navigation/): Advanced recipe for grouping existing pages into a different sidebar hierarchy without changing their URLs.
- [Guides](https://zudo-doc.takazudomodular.com/docs/guides/)

```mdx
<CategoryList category="guides" limit={6} scope="direct" layout="list" />
```

### Title only

Turn off descriptions and the archive link for a compact set of title cards.

- [Hide Sidebar](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/hide-sidebar/)
- [Hide Table of Contents](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/hide-toc/)
- [Hide Sidebar & TOC](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/hide-both/)
- [Wide Layout](https://zudo-doc.takazudomodular.com/docs/guides/layout-demos/wide/)

```mdx
<CategoryList category="guides/layout-demos" limit={6} showDescription={false} showArchive={false} />
```

### Extra metadata

Metadata is opt-in and shared by both layouts. Here the lead is turned off, so the date moves into the metadata row next to the tags.

- [Moving a Showcase Off Astro](https://zudo-doc.takazudomodular.com/docs/blog/migrating-from-astro/) (2026-03-27): A framework migration is easier to review when the content tree remains the stable center of the site.
- [Warn First, Error Later](https://zudo-doc.takazudomodular.com/docs/blog/tag-governance-warn-first/) (2026-03-10): Tag governance can start as a useful audit signal before it becomes a build gate.
- [Browse the blog](https://zudo-doc.takazudomodular.com/docs/blog/)

```mdx
<CategoryList category="blog" limit={2} lead="none" showDate showUpdated showTags archiveLabel="Browse the blog" />
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `category` | `string` | — | Canonical category slug, the path after `/docs/` without slashes at either end, for example `"blog"` or `"guides/layout-demos"`. Required. |
| `limit` | `number` | — | Maximum number of items, a positive integer. Required. |
| `layout` | `"cards" \| "list"` | `"cards"` | Presentation only; the items never change. |
| `scope` | `"descendants" \| "direct"` | `"descendants"` | Ordinary categories only. Note trays always list their own flat items. |
| `lead` | `"auto" \| "none" \| "rank" \| "date"` | `"auto"` | Leading detail. `"auto"` is the date for a dated tray, the number for an undated tray, and nothing for an ordinary category. |
| `showDescription` | `boolean` | `true` | Show the frontmatter `description` when there is one. |
| `showDate` | `boolean` | `false` | Show the `date` in the metadata row. Skipped when the date is already the lead. |
| `showUpdated` | `boolean` | `false` | Show the `updated` date with an "Updated" label. Skipped when it equals `date`. |
| `showTags` | `boolean` | `false` | Show the document's tags as plain text (not links). Needs `docTags`. |
| `showPath` | `boolean` | `false` | Show the subcategories between the listed category and the item. |
| `showCount` | `boolean` | `false` | Show "Showing N of total" in the footer. |
| `showArchive` | `boolean` | `true` | Show the footer link to the full category. |
| `archiveLabel` | `string` | `"See all"` | Text of the archive link. |
| `titleLevel` | `3 \| 4` | `3` | Heading level of item titles. |

## Which documents are listed

- The category is found by its exact slug. A page's frontmatter `slug` is respected, and a similar-looking slug never matches by prefix.
- Only pages a reader can navigate to are listed: drafts, `unlisted` and `standalone` pages are left out before counting. `search_exclude` affects search and exports only, so such pages still appear.
- The category's own landing page is never an item. Folders without an index page and generated category indexes are passed through but not listed. A subcategory with its own index page is listed once, in tree order.
- Order is the category's own order: `sidebar_position` and `category_sort_order`, exactly as in the sidebar. There is no separate sort option; a blog shows newest first when its tray is `category_sort_order: desc`.
- In a note tray, numbers come from the whole tray and keep their width. The first four items of a twelve-item descending tray show 12, 11, 10 and 09; they do not restart at 01. Ordinary categories never get numbers, even with `lead="rank"`.
- `limit` applies after filtering. When there are fewer documents than the limit, only those are shown. The count in the footer is the number of listed documents before the limit.
- Each locale lists its own translations, falling back to the default locale for untranslated pages, and an `unlisted` translation hides its fallback too. In a version, items and the archive link point into that version.

## Archive link

The footer link is an ordinary link to the category's own page, kept even when every item already fits, because the archive gives the full context. If the category has no page of its own (`category_no_page`), the items are still shown, the link is left out, and the build prints a `[zudo-doc]` warning. Set `showArchive={false}` to omit the link deliberately.

## Errors and empty categories

- An invalid option, such as a missing or non-integer `limit`, an unknown `layout` or an unknown prop, stops the build with an error naming the prop.
- An unknown category, or a slug that points at a document rather than a category, also stops the build. In another locale or an older version, where the category may legitimately be missing, nothing is rendered instead.
- A valid category with no visible documents renders nothing.

## On the homepage

The homepage intro Markdown cannot host components. Use a `category-list` entry in [`home.sections`](https://zudo-doc.takazudomodular.com/docs/guides/configuration/#home-page-home-composed-navigation-sections) instead. It takes the same options plus `heading`, `description` and per-locale `locales` overrides (`heading`, `description`, `archiveLabel`). The heading defaults to the category's own title. Entries are repeatable, and when a category has nothing to show, the whole section, heading included, is left out.

```ts
home: {
  sections: [
    {
      type: "category-list",
      category: "blog",
      limit: 3,
      heading: "Latest posts",
      showCount: true,
      archiveLabel: "See all posts",
      locales: { ja: { heading: "最新の記事", archiveLabel: "記事一覧へ" } },
    },
    { type: "site-tree", variant: "described" },
  ],
},
```

## Package API

Page modules can build the same component with `createCategoryListWrapper` from `@takazudo/zudo-doc/category-list`. The subpath also exports `resolveCategoryList` (pure resolution returning items, the total and the archive URL), `CategoryListView` (presentation), `assertValidCategoryListOptions`, and the `CategoryListOptions` types.