102 lines
1.7 KiB
Plaintext
102 lines
1.7 KiB
Plaintext
# 最佳实践
|
|
|
|
## 文档组织
|
|
|
|
### 合理的目录结构
|
|
|
|
建议按功能或主题组织文档：
|
|
|
|
```
|
|
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
|
|
|
|
```
|
|
|
|
### 代码高亮
|
|
|
|
指定语言以启用代码高亮：
|
|
|
|
\`\`\`javascript
|
|
const code = 'highlighted';
|
|
\`\`\`
|
|
|
|
## 可访问性
|
|
|
|
### 语义化 HTML
|
|
|
|
使用正确的标题层级和语义化标签。
|
|
|
|
### 描述性链接
|
|
|
|
避免使用"点击这里"这样的链接文本：
|
|
|
|
- ✅ [查看安装指南](/getting-started/installation)
|
|
- ❌ [点击这里](/getting-started/installation)
|
|
|
|
## 部署建议
|
|
|
|
### 静态托管
|
|
|
|
推荐使用以下静态托管服务：
|
|
- Vercel
|
|
- Netlify
|
|
- GitHub Pages
|
|
- Cloudflare Pages
|
|
|
|
### 构建命令
|
|
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
构建完成后，`out` 目录包含所有静态文件。 |