文档编写指南

文档内容都放在 content/docs 目录里。每个 .mdx 文件会自动变成一个文档页面。

文件和路由

常用规则：

• content/docs/index.mdx 对应 /docs
• content/docs/production.mdx 对应 /docs/production
• content/docs/writing-docs.mdx 对应 /docs/writing-docs
• content/docs/guide/index.mdx 对应 /docs/guide
• content/docs/guide/install.mdx 对应 /docs/guide/install

新增一篇文档

在 content/docs 下创建一个新的 .mdx 文件，例如 deploy.mdx：

---
title: 部署说明
description: 项目部署到生产环境的步骤
---

这里写正文。

## 第一步

说明具体步骤。

保存后，开发服务器会自动更新页面和搜索索引。

控制侧边栏顺序

侧边栏顺序由 content/docs/meta.json 控制：

{
  "title": "文档",
  "pages": ["index", "production", "writing-docs", "test"]
}

新增文档后，把文件名加入 pages 数组即可。文件名不需要写 .mdx 后缀。

常用 MDX 写法

标题

## 二级标题

### 三级标题

标题会自动生成右侧目录。

链接

[返回开始使用](./)
[查看生产上线清单](./production)

代码块

```ts
export const siteName = '我的文档站';
```

卡片

<Cards>
  <Card title="生产上线清单" href="/docs/production" />
  <Card title="文档编写指南" href="/docs/writing-docs" />
</Cards>

写作建议

• 每篇文档只讲一个主题
• title 写短一点，方便侧边栏阅读
• description 写清楚页面用途
• 用二级标题拆分步骤
• 命令统一放进代码块
• 不要把密码、Token、密钥写进文档

写完后检查

写完或上线前运行：

npm.cmd run types:check
npm.cmd run lint

如果要确认生产构建：

npm.cmd run build