@rodavel/tanstack-mdx-tree

Vite plugin that generates typed navigation trees from MDX content colocated with your TanStack Router routes.

Why

Colocates MDX documentation with TanStack Router routes following the same file-system conventions. _meta.json files provide display names and ordering per directory. The plugin scans the structure and outputs a typed tree and page map for use in navigation components.

Install

bun add @rodavel/tanstack-mdx-tree

Usage

// vite.config.ts
import { contentTreeGeneratorPlugin } from "@rodavel/tanstack-mdx-tree";

export default defineConfig({
  plugins: [
    contentTreeGeneratorPlugin({
      docsDir: "src/routes/docs",
      outFile: "src/generated/docs-tree.gen.ts",
    }),
  ],
});

The plugin scans docsDir for page files (default index.mdx) with YAML frontmatter, builds a nested navigation tree, and writes it to outFile as a TypeScript module. It regenerates on every content or metadata change during dev.

URL prefix derivation

The URL prefix is derived from docsDir relative to routesDir (default src/routes). For example, src/routes/docs produces the prefix /docs, so a page at src/routes/docs/guides/index.mdx gets the URL /docs/guides.

Root tree node

The root tree node name comes from the root _meta.json file's name field. If no root _meta.json exists, the directory name is used (e.g., docs).

src/routes/docs/
├── _meta.json          # { "name": "Documentation" }
├── index.mdx           # Root page → becomes tree.index
├── guides/
│   ├── _meta.json      # { "name": "Guides", "order": 1 }
│   ├── index.mdx
│   └── setup/
│       └── index.mdx
└── api/
    ├── _meta.json      # { "name": "API Reference", "order": 2 }
    └── index.mdx

Directory metadata (_meta.json)

Each directory can contain a _meta.json file to configure its tree node:

| Field | Type | Description | | --- | --- | --- | | name | string | Display label for the directory node | | order | number | Sort order (lower values appear first) |

Any additional fields are passed through as extra on the DirectoryMeta object:

{
  "name": "Guides",
  "order": 1,
  "icon": "book"
}

Here icon would be available as extra.icon.

Options

Required

| Option | Type | Description | | --- | --- | --- | | docsDir | string | Path to the content directory to scan | | outFile | string | Path where the generated TypeScript file is written |

Optional

| Option | Type | Default | Description | | --- | --- | --- | --- | | routesDir | string | "src/routes" | TanStack Router routes directory, used to derive the URL prefix | | metaFile | string | "_meta.json" | Filename for directory metadata | | pageFile | string | "index.mdx" | Filename to match as a page entry | | enrichPages | (pages, pageByKey) => void | no-op | Callback invoked after scanning and before tree building; mutate pages in place (e.g., inherit fields from ancestors). Receives the pages array and a Map<string, ScannedPage> for O(1) lookups |

CLI

Generate the content tree from the command line using your existing Vite config:

npx content-tree

The CLI reads the contentTreeGeneratorPlugin options from your vite.config.ts and runs the generator. Useful for CI or scripts that need to generate the tree outside of a Vite build.

Compatibility

• Vite 5+
• Node.js 18+

License

MIT