云端自留地配置项
这个模板的配置不用背。你只要知道“该去哪改”，基本就够用了。
别一看到 app/、source.config.ts、content/ 就开始头大。它们分工其实很简单：
content/docs 写文档
content/docs/meta 控制侧栏
app/layout.tsx 站点级 metadata
source.config.ts Fumadocs 内容源和 MDX 插件
app/global.css 全局样式页面标题和描述
每个 .mdx 文件开头都有 frontmatter：
---
title: 配置项
description: 怎么把这个模板变成你的形状。
---这里的 title 会影响页面标题和侧栏显示。description 用来做页面摘要，也方便搜索和 SEO。
建议写法：
---
title: 部署指南
description: 把文档站部署到 Pages 平台前需要检查的东西。
---不建议写法：
---
title: 啊啊啊啊啊
description: 随便
---你当然可以这么写，但以后自己回来翻文档时会想揍过去的自己。
侧栏顺序
侧栏主要看 meta.json。
顶层例子：
{
"title": "文档",
"pages": ["index", "getting-started", "components", "deployment"]
}子目录例子：
{
"title": "开始使用",
"pages": ["quick-start", "configuration", "writing-workflow"]
}pages 里的名字对应文件名，不要带 .mdx。
小坑
新增页面后，如果侧栏顺序不对，先检查同目录下的 meta.json。别急着怀疑 Fumadocs，很多时候只是自己忘了登记。
站点级 metadata
站点标题、描述这类东西通常在 app/layout.tsx。
你可以找类似这样的配置：
export const metadata = {
title: 'Nyaovo Docs',
description: '一些项目说明和折腾记录。',
};这里不是文章标题，是整个站点在浏览器、搜索引擎、分享卡片里看到的信息。
Fumadocs 内容源
source.config.ts 负责告诉 Fumadocs 文档在哪，以及 MDX 要启用哪些插件。
当前模板大概是这种思路：
export const docs = defineDocs({
dir: 'content/docs',
});意思是：文档内容从 content/docs 读。
如果你只是写文章，别碰它。只有你要换目录、加 MDX 插件、折腾数学公式渲染时，才需要看这里。
Markdown 和 MDX
普通 Markdown 当然能写：
## 一个标题
- 一条列表
- 又一条列表MDX 还能在文档里用 React 组件：
import { Callout } from 'fumadocs-ui/components/callout';
<Callout title="提示" type="info">
这里可以写更醒目的说明。
</Callout>这就是 Fumadocs 比普通静态 Markdown 站更灵活的地方。代价是：写错 JSX 标签会直接构建失败。高级是高级，脾气也不小。
推荐命名规则
页面文件名建议：
quick-start.mdx
writing-workflow.mdx
deploy-checklist.mdx不要写：
快速开始.mdx
新建 文档.mdx
最终版2真的最终版.mdx中文标题放在 frontmatter，文件名保持英文小写加中划线。这个习惯很朴素，但能少很多路由和部署平台的破事。
什么时候需要新建页面
适合新建页面：
- 这个主题能写超过三屏。
- 它以后可能被别人单独搜索到。
- 它和当前页面不是同一类内容。
- README 已经开始变得又长又臭。
不适合新建页面：
- 只有两句话。
- 只是临时想法。
- 写完一次以后再也不会维护。
这种东西丢 Memos 或 README 就行，别把文档站变成杂物间。
最稳的改法
每次只做一类改动：
先新增页面
再调整侧栏
再改样式
最后跑构建不要一口气改十个文件然后问“为什么炸了”。那不是排障，是考古。