suzuri-docs
Documentation site for Suzuri, built with
Fumadocs on Next.js.
Develop
pnpm install
pnpm dev # http://localhost:3000
pnpm build # production build
pnpm types:check # next typegen && tsc --noEmit
pnpm lint # eslint
Writing docs
Pages are MDX files under content/docs. The file path becomes the URL
(content/docs/writing/citations.mdx → /writing/citations), and each page's
frontmatter drives the sidebar:
---
title: Citations
description: One sentence, also used for the OG image and llms.txt.
icon: Quote
---
icon is a Lucide name in PascalCase, and it must exist
in lucide-react's icons map — the build warns on unknown names (Home is
House, for instance).
meta.json in a folder sets that section's title, icon, and page order.
Ordering is explicit; new pages need to be added to the list.
Components available in MDX (Callout, Cards/Card, Tabs/Tab, Steps,
Files, Accordions, TypeTable, Mermaid) are registered in
components/mdx.tsx. Card's icon prop takes JSX, not a name — import from
lucide-react at the top of the MDX file.
Mermaid draws a diagram in the browser and follows the light/dark theme. It
takes the diagram source as a chart prop rather than a fenced code block, so
a ```mermaid fence still shows as source — which is what a page about
Suzuri's own syntax usually wants:
<Mermaid
chart={`flowchart LR
a --> b`}
/>
Layout of the project
| Path | What it is |
|---|
content/docs | The docs themselves |
lib/source.ts | Content source and page tree |
lib/shared.ts | Site name, URLs, GitHub coordinates |
lib/layout.shared.tsx | Nav title, logo, header links |
app/(docs) | Docs layout and page route, served at the site root |
app/global.css | Suzuri palette and prose typography |
app/api/search | Search index endpoint |
app/llms.txt, app/llms-full.txt, app/llms.mdx | Machine-readable docs |
app/og | Generated OG images |
Appending .md to any docs URL — or requesting it with an Accept header that
prefers markdown — returns the page's markdown source, via proxy.ts.
URLs
The whole site is documentation, so docs are served at the root
(/installation, not /docs/installation). That is set by docsRoute in
lib/shared.ts and the app/(docs) route group.
Because the docs catch-all sits at the root, proxy.ts keeps a RESERVED list
of prefixes it must not rewrite (/api, /og, /llms.txt, /llms-full.txt,
/llms.mdx). Add to it if you add a route handler of your own.
Deploying
Deployed on Vercel as its own project at docs.suzuri.ai. It is a stock
Next.js app — Vercel's defaults (pnpm build, no output directory override)
are correct. siteUrl in lib/shared.ts feeds metadataBase, so update it if
the domain changes.
