Documentation Guidelines

Follow this when adding or restructuring docs. The site is Astro Starlight; demos come from registry example files under src/registry/new-york/examples/.

Information architecture

Split API / overview from runnable examples. Do not put the same topic in both sidebars.

Section	Purpose	Path
Niko Table	Introduction + overview by layer (Components, Core, …)	src/content/docs/niko-table/
Examples	Table demos (Simple Table, Faceted Filter, …)	src/content/docs/examples/
Data Grid	Introduction + overview by layer + API Reference	src/content/docs/data-grid/
Data Grid Examples	Grid demos (Basic Grid, Cell Types, Validation, …)	src/content/docs/examples/

Data Grid overview pages mirror the source tree (grid/components, grid/core, grid/hooks, …). Feature walkthroughs with a live demo belong under Data Grid Examples, not under overview.

Reference: Basic Grid: minimal grid example that follows this guide.

File layout

src/content/docs/
  niko-table/overview/          # table API by layer
  data-grid/
    introduction.mdx
    api.mdx
    overview/                   # grid API by layer
  examples/
    simple-table.mdx            # table example
    basic-grid.mdx              # grid example (*-grid.mdx)
src/registry/new-york/examples/niko-table/
  simple.tsx                    # demo wired by CodePreview
  grid-basic.tsx
  grid-basic-state.tsx          # optional collapsible “state” pane

• Table example slugs: examples/<feature>-table (or existing names like simple-table).
• Grid example slugs: examples/<feature>-grid.
• Overview never duplicates an example’s full tutorial; link across instead.

Adding a Data Grid Example

1. Registry demo: add a self-contained example under src/registry/new-york/examples/niko-table/ (e.g. grid-foo.tsx). Import only from @/components/niko-table/... direct paths and @/components/ui. Use deterministic mock data (no Math.random() / Date.now()).

2. Register the demo name: add the string to the Demo union in src/components/markdown/code-preview/_code-preview-internal.tsx, and wire the lazy import map there.

3. Example MDX: create src/content/docs/examples/<name>-grid.mdx with:

   • Short pitch (1–2 sentences)
   • <CodePreview demo="niko-table/…" />
   • Optional <CollapsiblePreview> + state demo
   • Installation (CliCommandCode)
   • Optional short “What’s included” / usage notes
   • Next links to related overview or examples

4. Sidebar: add an entry under Data Grid Examples in astro.config.mts (slug: "examples/<name>-grid"). The slug must match a file at src/content/docs/<slug>.mdx or src/content/docs/<slug>/index.mdx. A missing file throws Starlight’s The slug "…" specified in the Starlight sidebar config does not exist error (clear .astro/ and restart pnpm dev if the file exists but the error persists).

5. Cross-links: from Introduction / overview pages, link to the example; don’t paste a second live demo of the same feature into overview.

Page patterns

Overview (API by layer)

• Source Code / related DocsLink row at the top when useful
• Props tables and import paths by file
• Point to examples for “see it running”

Example (demo-first)

• Demo first, prose after
• Installation for that example’s registry items only
• Keep deeper theory in overview; keep the example focused

Links

Prefer trailing slashes in hardcoded hrefs and markdown links, e.g. /examples/basic-grid/. Dev can accept both with trailingSlash: "ignore", but slashed links stay consistent with production directory URLs.

Punctuation

Avoid em dashes (—). Prefer a colon after bold labels (**Composable**: …), or a period / comma in prose.

Sidebar scroll

Theme-black does not use Starlight’s #starlight__sidebar / SidebarPersister. Do not add that id: it freezes the main thread with this theme.

Scroll restore for the theme sidebar lives in src/components/overrides/head.astro (aside.aside .sidebar + sessionStorage). Prefer extending that script over a custom Sidebar override.

Checklist before PR

• Overview vs Examples split is clear (no duplicate nav items)
• Demo is registered and renders in CodePreview
• Mock data is deterministic
• Sidebar entry added in astro.config.mts and pnpm run check:sidebar passes
• Internal links point at the new paths (homepage / changelog / related Next Steps when relevant)
• pnpm run build (or at least astro check) passes

Related

• Contributing Code: fork, branch, registry build
• Component Request / Feature Request
• CLAUDE.md: component layering and registry rules