# 最佳实践

## 文档组织

### 合理的目录结构

建议按功能或主题组织文档：

```
app/
├── getting-started/     # 入门相关
├── guide/               # 使用指南
├── api/                 # API 文档
└── examples/            # 示例代码
```

### 清晰的命名

使用简洁、清晰的文件名：
- ✅ `installation.mdx`
- ✅ `quick-start.mdx`
- ❌ `page1.mdx`
- ❌ `how-to-install-this-thing.mdx`

## 内容编写

### 使用标题层级

- `#` 用于页面标题（每个页面只有一个）
- `##` 用于主要章节
- `###` 用于子章节

避免跳级使用标题。

### 添加代码示例

代码示例应清晰、完整、可运行：

```javascript
// ✅ 好的示例
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet('World')); // 输出: Hello, World!
```

### 使用表格展示数据

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `theme` | string | 主题名称 |
| `logo` | ReactNode | 站点 Logo |

## 性能优化

### 图片优化

使用 WebP 格式，压缩图片大小：

```markdown
![示例图片](./image.webp)
```

### 代码高亮

指定语言以启用代码高亮：

\`\`\`javascript
const code = 'highlighted';
\`\`\`

## 可访问性

### 语义化 HTML

使用正确的标题层级和语义化标签。

### 描述性链接

避免使用"点击这里"这样的链接文本：

- ✅ [查看安装指南](/getting-started/installation)
- ❌ [点击这里](/getting-started/installation)

## 部署建议

### 静态托管

推荐使用以下静态托管服务：
- Vercel
- Netlify
- GitHub Pages
- Cloudflare Pages

### 构建命令

```bash
pnpm build
```

构建完成后，`out` 目录包含所有静态文件。