SiteTreeNav

Created Mar 14, 2026Updated Jul 24, 2026Takeshi Takatsudo

A sitemap-like grid component that displays the full documentation tree with expandable categories.

Overview

SiteTreeNav is a Preact island component that renders a responsive grid of expandable category cards showing the full documentation tree. It provides a sitemap-style index of all documentation pages, with categories that can be expanded and collapsed.

Info

SiteTreeNav is directly available in MDX content — it's registered as a global MDX tag, so <SiteTreeNav /> works with no import. The SiteTreeNavDemo tag used in the live example below resolves to the exact same self-fetching wrapper; the two names are interchangeable in MDX.

This is a different component from the raw, tree-prop-driven SiteTreeNav shipped at @takazudo/zudo-doc/site-tree-nav-island — that one takes no data by itself and is meant for a page module that already has a nav tree to pass in. See Usage below for both.

Live Example

Below is SiteTreeNav rendered with the full documentation tree (same as the home page):

Usage

In MDX content

Use the global MDX tag directly in any .mdx file — no import needed:

<SiteTreeNav />

No props are required. It self-fetches the current locale's docs collection, builds the nav tree, and renders the interactive island — the same wrapper used by SiteTreeNavDemo above.

In a page module

A page module that already has a tree in hand (e.g. built via buildNavTree + groupSatelliteNodes) can import the raw, tree-prop-driven component instead:

import { SiteTreeNav } from "@takazudo/zudo-doc/site-tree-nav-island";

export default function IndexPage() {
  return (
    <SiteTreeNav
      tree={tree}
      categoryOrder={categoryOrder}
      categoryIgnore={["inbox", "develop"]}
    />
  );
}

This repository's own home page (pages/index.tsx) doesn't call this island directly — it hands the resolved locale to prepareHomeData() and passes the result to HomePageView, both from @takazudo/zudo-doc/home-page, which renders SiteTreeNav internally alongside the hero and tag section.

The component uses Preact state for expand/collapse interactivity, so it hydrates on the client through zfb's island runtime.

Props

Props below apply to the raw SiteTreeNav island (@takazudo/zudo-doc/site-tree-nav-island). The MDX tag takes no data props — it resolves tree/categoryOrder itself for the current locale, and only forwards an optional ariaLabel.

Prop	Type	Default	Description
`tree`	`NavNode[]`	(required)	The navigation tree built from content collection
`categoryOrder`	`string[]`	—	Custom ordering of top-level categories
`categoryIgnore`	`string[]`	—	Category slugs to hide from the tree
`initiallyCollapsedCategorySlugs`	`string[]`	—	Root-category slugs that should start collapsed
`ariaLabel`	`string`	`"Site index"`	Accessibility label for the nav element

Features

Responsive grid layout — uses repeat(auto-fill, minmax(min(18rem, 100%), 1fr)) to adapt from single-column on mobile to multi-column on wider screens
Expandable categories — each category card is collapsible, open by default
Hierarchical tree — nested pages are indented with connector lines showing the tree structure
Category links — top-level categories display an arrow icon and link to their index page
Leaf pages — individual doc pages are rendered as clickable links

Source

SiteTreeNav ships from the @takazudo/zudo-doc package — import the raw island from @takazudo/zudo-doc/site-tree-nav-island for page-module usage. (Within this repository the island source lives at packages/zudo-doc/src/site-tree-nav-island/.) The <SiteTreeNav /> / <SiteTreeNavDemo /> MDX tags are wired automatically via the package-owned routes (packageOwnedRoutes, on by default) — there is no project file to maintain for them.

View source on GitHub