CategoryList
A server-rendered excerpt of one category, as cards or a two-column list, with a link to the full category. Built for blog posts, numbered notes and ordinary categories.
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
A framework migration is easier to review when the content tree remains the stable center of the site.Warn First, Error Later
Tag governance can start as a useful audit signal before it becomes a build gate.Keeping Doc History Out of the Build
Git history stays useful when expensive per-document work runs outside the main site build.
<CategoryList category="blog" limit={3} showTags showCount />Blog as a list
Moving a Showcase Off Astro
A framework migration is easier to review when the content tree remains the stable center of the site.Warn First, Error Later
Tag governance can start as a useful audit signal before it becomes a build gate.Keeping Doc History Out of the Build
Git history stays useful when expensive per-document work runs outside the main site build.Designing the 16rem Drawer
A fixed-width sidebar drawer keeps navigation predictable without taking over the document.
<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
Learn what zudo-doc is, its features, and how it works. - 02
Installation
How to install and set up zudo-doc for local development. - 03
Setup Preset Generator
Interactive helper to generate setup presets for create-zudo-doc. - 04
Writing Docs
How to create and organize documentation pages in zudo-doc.
<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
The single zudoDoc() config reference — every field and its default.Custom Components
Add presentational MDX components, overrides, and experimental interactive islands.Frontmatter
Complete reference for all available frontmatter fields in zudo-doc documents.Sidebar
How the sidebar navigation is structured and configured.Note Trays
Build flat, ordered categories for notes, journals, and other sequential writing.Editorial Navigation
Advanced recipe for grouping existing pages into a different sidebar hierarchy without changing their URLs.
<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.
<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.
<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 / 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
slugis respected, and a similar-looking slug never matches by prefix.Only pages a reader can navigate to are listed: drafts,
unlistedandstandalonepages are left out before counting.search_excludeaffects 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_positionandcategory_sort_order, exactly as in the sidebar. There is no separate sort option; a blog shows newest first when its tray iscategory_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".limitapplies 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
unlistedtranslation 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 unknownlayoutor 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 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.
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/. The subpath also exports resolveCategoryList (pure resolution returning items, the total and the archive URL), CategoryListView (presentation), assertValidCategoryListOptions, and the CategoryListOptions types.