## Overview

`SiteTreeNav` is a client 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.

[Dynamic content unavailable in text export]

`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](https://zudo-doc.takazudomodular.com/docs/components/site-tree-nav#usage) below for both.



## Live Example

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

[Dynamic content unavailable in text export]

## Usage

### In MDX content

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

```mdx
<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.

Categories hidden from the tree come from [`siteTreeNavIgnore`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#home-page-sitetreenavignore) in `zfb.config.ts`. [`siteTreeNavSecondary`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#home-page-sitetreenavsecondary) is home-page only and is not applied by this component, so categories listed there still appear in its tree.

### 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:

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

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

The raw island's `categoryIgnore` prop is the per-call equivalent of the site-wide [`siteTreeNavIgnore`](https://zudo-doc.takazudomodular.com/docs/guides/configuration#home-page-sitetreenavignore) setting; the package home page and the MDX tag pass that setting here.

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 signals 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 (the package home page and the MDX tag pass `siteTreeNavIgnore` here) |
| `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.