lobe-editor / rules

---
description: Documentation standards and formatting guidelines for LobeHub Editor
globs: *.md,*.mdx
---

# Documentation Standards

The docs site (<https://editor.lobehub.com>) is built with `@lobehub/docs-kit` (`lobedocs`).
Follow [AGENTS.md](mdc:AGENTS.md) ("Writing Docs") and the
[using-docs-kit skill](mdc:.agents/skills/using-docs-kit/SKILL.md); this rule summarises them.

## Where Pages Live

- One `index.mdx` per documented folder. Only files named `index.mdx` become pages
  (`index.md` is ignored).
- [docs.config.ts](mdc:docs.config.ts) `atomDirs` are `src/react`, `src/plugins` and
  `src/renderer`, so:
  - `src/plugins/hr/index.mdx` → `/components/plugins/hr`
  - `src/react/SendButton/index.mdx` → `/components/react/send-button`
- Site-level pages live in `docs/` (`docs/components.mdx`, `docs/changelog.mdx`); the home page
  is `docs/index.tsx`.

## Frontmatter

```yaml
---
title: Horizontal Rule
description: One or two plain sentences; used for search, SEO and llms.txt.
category: Plugins
---
```

- Required: `title`, `description`, `category`.
- Reuse existing categories: `Core`, `Plugins` (plugins); `General`, `Data Entry`, `Layout`,
  `Playground`, `Providers` (React components); `Renderer`.
- Do not use dumi fields (`nav`, `group`, `atomId`).

## Demos

- Put demos in `<folder>/demos/` (`index.tsx` for the basic one), one `export default`
  component per file.
- Import the library by package name (`@lobehub/editor`, `@lobehub/editor/react`); the docs
  config aliases it to `src`.
- Reference demos with the `?demo` query and `<Demo of>`:

```mdx
import DemoIndex from './demos/index.tsx?demo';

## Basic Usage

<Demo editable={false} of={DemoIndex} />
```

- Common `<Demo>` props: `editable={false}` for editor playgrounds, `layout="bare"` for
  full-width demos, `isolated` for demos that use portals or global CSS.
- Do not use dumi `<code src="...">`.

## Page Structure

- The `title` is the H1; start the body at `##`.
- Typical sections: `## Introduction`, `## Basic Usage`, feature sections, then `## APIs`.
- API tables are written by hand and must match the TypeScript types:

```markdown
| Property     | Description           | Type      | Default |
| ------------ | --------------------- | --------- | ------- |
| enableHotkey | Enable list shortcuts | `boolean` | `true`  |
```

- Escape `|` inside table cells as `\|` (e.g. `` `'top' \| 'bottom'` ``).
- Code fences need a language (`tsx`, `typescript`, `bash`, ...).

## Checking

```bash
pnpm dev          # lobedocs dev; restart after editing docs.config.ts
pnpm docs:build   # runs all docs validations (frontmatter, demo references, links)
pnpm lint:md      # remark lint on Markdown files
```

- Do not hand-edit `compatibility.json` (legacy URL inventory) unless you move or rename an
  existing page.
- `skills.md` and `llms.txt` on the docs site are generated by `lobedocs build`; do not write
  them by hand.

## README

`README.md` covers installation, a quick start and links; detailed API docs belong on the docs
site. Update the README only when installation or the quick-start example changes.