Documentation

The site you're reading is built from github.com/ProjectKumo/Kumo-docs with Fumadocs on top of Next.js.

If you spot a typo, a missing step, or a passage that confused you, you're already qualified to fix it.

Running the site locally

git clone https://github.com/ProjectKumo/Kumo-docs.git
cd Kumo-docs
pnpm install
pnpm dev

Open http://localhost:3000 and edit any file under content/docs/. The page hot-reloads as you type.

If you don't have pnpm, install it once with npm install -g pnpm.

Site layout

Kumo-docs/
  content/
    docs/
      index.mdx            Landing page
      meta.json            Top-level navigation order
      getting-started/     Plain-language user docs
      advanced/            Advanced track docs
      contributing/        These pages
  app/                     Next.js App Router shell
  components/              Shared React components
  lib/                     Layout config (nav title, GitHub URL, app name)
  public/                  Static assets — favicon, logo PNGs
  source.config.ts         Fumadocs MDX source configuration
  next.config.mjs          Next.js config (wraps Fumadocs MDX)

Most contributions only touch files inside content/docs/.

How pages work

Every page is an .mdx file with a YAML frontmatter block:

---
title: Page title shown in the sidebar
description: One-line summary used by SEO and the page header
---

import { Callout } from 'fumadocs-ui/components/callout';

Body content. Markdown plus React components.

The nav order inside a folder comes from a sibling meta.json:

{
  "title": "Getting Started",
  "description": "...",
  "pages": [
    "index",
    "install",
    "subscriptions",
    "---Day to day---",
    "daily-use",
    "outbound-modes"
  ]
}

"---Section---" entries are non-clickable section headings inside the sidebar.

Useful components

These ship with Fumadocs and we use them throughout:

import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Steps, Step } from 'fumadocs-ui/components/steps';

<Callout type="info">A blue informational note.</Callout>
<Callout type="warn">A yellow warning. Use for footguns, not nags.</Callout>

<Cards>
  <Card title="Title" href="/docs/...">One-line teaser.</Card>
</Cards>

<Steps>
<Step>### First step</Step>
<Step>### Second step</Step>
</Steps>

Use them when they earn their keep. A page does not need every available component.

MDX footguns

Two parser quirks bit us during the initial migration:

• Bare autolinks break MDX. <https://example.com> is parsed as a JSX tag. Always write [example.com](https://example.com) or wrap the URL in backticks.
• | characters inside <…> blocks break MDX. <auto|always|never> is parsed as JSX. Use <auto/always/never> or plain text instead.

When the build fails, the error usually points to the exact line.

Style notes

We write three different voices in three different places:

Across all three:

• Use second person ("you do X").
• Active voice.
• Concrete examples over abstract description. A YAML snippet beats a paragraph about what YAML could look like.
• Link the obvious things. Cross-references inside Kumo-docs use the /docs/... form.
• Keep paragraphs short. Four to five lines is a soft cap.

Before opening the PR

Run the build locally:

pnpm build

The build:

1. Compiles every .mdx page.
2. Generates type definitions for Fumadocs MDX.
3. Builds the Next.js production output.

If pnpm build is green, the site will render.

Optional but appreciated:

pnpm types:check
pnpm lint

Reviewing your own writing

Two passes that catch most issues:

1. Read it out loud. Sentences that sound clumsy on the tongue almost always read clumsy on the screen.
2. Skim it five minutes after writing it. Things that felt clever at the keyboard often turn out to be filler.