fumadocs-component-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Documentation Pattern

组件文档编写规范

Create comprehensive documentation for 8-bit components following the standard structure.

为8-bit组件创建全面的文档，遵循以下标准结构。

Component Preview Structure

组件预览结构

Wrap component examples in ComponentPreview with realistic data:

mdx

<ComponentPreview title="8-bit ComponentName component" name="component-name">
  <div className="md:min-w-[300px] min-w-[200px] flex flex-col gap-8">
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        Description of first variant
      </p>
      <ComponentName prop={value} />
    </div>
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        Description of second variant
      </p>
      <ComponentName prop={value} variant="retro" />
    </div>
  </div>
</ComponentPreview>

使用ComponentPreview包裹组件示例，并填入真实数据：

mdx

<ComponentPreview title="8-bit ComponentName component" name="component-name">
  <div className="md:min-w-[300px] min-w-[200px] flex flex-col gap-8">
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        第一个变体说明
      </p>
      <ComponentName prop={value} />
    </div>
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        第二个变体说明
      </p>
      <ComponentName prop={value} variant="retro" />
    </div>
  </div>
</ComponentPreview>

Simple Component Example

简单组件示例

For basic components like Button:

mdx

<ComponentPreview title="8-bit button component" name="button">
  <Button>Button</Button>
</ComponentPreview>

针对Button这类基础组件：

mdx

<ComponentPreview title="8-bit button component" name="button">
  <Button>Button</Button>
</ComponentPreview>

Complex Component Example

复杂组件示例

For components with multiple sub-components like Sheet:

mdx

<ComponentPreview title="8-bit Sheet component" name="sheet">
  <Sheet>
    <SheetTrigger asChild>
      <Button variant="outline">Open</Button>
    </SheetTrigger>
    <SheetContent>
      <SheetHeader>
        <SheetTitle>Edit profile</SheetTitle>
        <SheetDescription className="text-xs">
          Make changes to your profile here.
        </SheetDescription>
      </SheetHeader>
      <div className="p-4 flex flex-col gap-4">
        <Label>Name</Label>
        <Input placeholder="Project name" />
      </div>
      <SheetFooter className="flex-row-reverse">
        <SheetClose asChild>
          <Button size="sm">Save changes</Button>
        </SheetClose>
      </SheetFooter>
    </SheetContent>
  </Sheet>
</ComponentPreview>

针对包含多个子组件的Sheet这类组件：

mdx

<ComponentPreview title="8-bit Sheet component" name="sheet">
  <Sheet>
    <SheetTrigger asChild>
      <Button variant="outline">Open</Button>
    </SheetTrigger>
    <SheetContent>
      <SheetHeader>
        <SheetTitle>Edit profile</SheetTitle>
        <SheetDescription className="text-xs">
          在此处修改你的个人资料。
        </SheetDescription>
      </SheetHeader>
      <div className="p-4 flex flex-col gap-4">
        <Label>名称</Label>
        <Input placeholder="项目名称" />
      </div>
      <SheetFooter className="flex-row-reverse">
        <SheetClose asChild>
          <Button size="sm">保存修改</Button>
        </SheetClose>
      </SheetFooter>
    </SheetContent>
  </Sheet>
</ComponentPreview>

Usage Section Pattern

使用板块规范

Single import (simple components):

mdx

```tsx
import { Button } from "@/components/ui/8bit/button"


**Multiple imports** (complex components):

```mdx
```tsx
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/8bit/sheet"

undefined

单个导入（适用于简单组件）：

mdx

```tsx
import { Button } from "@/components/ui/8bit/button"


**多个导入**（适用于复杂组件）：

```mdx
```tsx
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/8bit/sheet"

undefined

Props Documentation

属性文档

For components with props tables, use tables:

mdx

undefined

对于需要展示属性表的组件，使用表格：

mdx

undefined

Props

Prop	Type	Default	Description
variant	`string`	`"default"`	Visual style variant
size	`string`	`"default"`	Size of the button
asChild	`boolean`	`false`	Whether to merge props onto child

undefined

属性	类型	默认值	说明
variant	`string`	`"default"`	视觉样式变体
size	`string`	`"default"`	按钮尺寸
asChild	`boolean`	`false`	是否将属性合并到子元素上

undefined

Variant Examples

变体示例

Show multiple variants in preview:

mdx

<ComponentPreview title="8-bit Health Bar component" name="health-bar">
  <div className="md:min-w-[300px] min-w-[200px] flex flex-col gap-8">
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        Default health bar
      </p>
      <HealthBar value={75} />
    </div>
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        Retro health bar
      </p>
      <HealthBar value={45} variant="retro" />
    </div>
  </div>
</ComponentPreview>

在预览中展示多个组件变体：

mdx

<ComponentPreview title="8-bit Health Bar component" name="health-bar">
  <div className="md:min-w-[300px] min-w-[200px] flex flex-col gap-8">
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        默认生命值条
      </p>
      <HealthBar value={75} />
    </div>
    <div>
      <p className="text-sm text-muted-foreground mb-2">
        复古风格生命值条
      </p>
      <HealthBar value={45} variant="retro" />
    </div>
  </div>
</ComponentPreview>

Copy Command Button

复制命令按钮

Place before ComponentPreview:

mdx

<div className="flex flex-col md:flex-row items-center justify-end gap-2 mb-2">
  <CopyCommandButton
    copyCommand="pnpm dlx shadcn@latest add @8bitcn/component-name"
    command="pnpm dlx shadcn@latest add @8bitcn/component-name"
  />
</div>

将其放置在ComponentPreview之前：

mdx

<div className="flex flex-col md:flex-row items-center justify-end gap-2 mb-2">
  <CopyCommandButton
    copyCommand="pnpm dlx shadcn@latest add @8bitcn/component-name"
    command="pnpm dlx shadcn@latest add @8bitcn/component-name"
  />
</div>

Key Principles

核心原则

Preview first - Show component before explaining
Multiple variants - Demonstrate different prop combinations
Realistic data - Use meaningful values in examples
Import completeness - Include all used imports
Code block labels - Use ```tsx for TypeScript
8-bit components - Import from
```
@/components/ui/8bit/
```
Consistent spacing - Use gap-4, p-4, mb-2 patterns

预览优先 - 先展示组件，再进行说明
多变体展示 - 演示不同属性组合的效果
真实数据 - 在示例中使用有意义的数值
完整导入 - 包含所有用到的导入语句
代码块标签 - 使用```tsx标识TypeScript代码
8-bit组件 - 从
```
@/components/ui/8bit/
```
路径导入
统一间距 - 使用gap-4、p-4、mb-2这类间距规范

Reference Examples

参考示例

```
content/docs/components/button.mdx
```
- Simple component pattern
```
content/docs/components/health-bar.mdx
```
- Variant demonstration
```
content/docs/components/sheet.mdx
```
- Complex sub-component pattern

```
content/docs/components/button.mdx
```
- 简单组件编写规范
```
content/docs/components/health-bar.mdx
```
- 变体演示规范
```
content/docs/components/sheet.mdx
```
- 复杂子组件编写规范