写作工作流

文档不是一口气憋出来的。尤其是个人项目，很多内容一开始都只是几句碎碎念、踩坑记录、命令备忘。

比较舒服的流程是：先随便记，后面再整理。别一开始就摆出“我要写企业级文档”的架势，吓人，也没必要。

从哪里开始写

可以按这个顺序来：

不要先写背景故事，先写这个页面解决什么问题。

这页记录如何把文档站部署到 EdgeOne Pages。

一句话能说清楚，就别先铺垫八段。

命令、路径、配置项优先。

pnpm install
pnpm build

文档最基本的尊严是：别人照着做不会立刻掉坑里。

等你真踩过坑，再把坑写进去。

如果构建失败，先看 MDX 标签有没有闭合。

别硬编“常见问题”。没遇到就别写，写多了像客服模板。

普通项目文档可以按这个结构：

# 页面标题

这页解决什么问题。

## 使用场景

什么时候需要它。

## 操作步骤

一步一步写。

## 常见坑

真实踩过的坑。

## 下一步

链接到相关页面。

不用每页都照抄这个结构，但它能防止你写着写着变成散文。

这个最容易乱。建议这么分：

Memos  = 临时想法、碎片记录、今天踩了什么坑
README = 项目的最小说明，别人进仓库第一眼要看的东西
Docs   = README 放不下的长内容、跨项目说明、部署和配置细节
Blog   = 正式文章、经验复盘、带个人表达的长文

别把所有东西都塞进 Docs

文档站不是垃圾桶。两句话能说完的东西，README 或 Memos 就够了。真有复用价值、需要长期维护，再放进 Docs。

如果项目只有这些内容：

那 README 就够。别为了显得高级硬开文档站。

当项目出现这些情况，Docs 才开始有意义：

这时候 Fumadocs 就派上用场了。

这个站不用太正经。个人项目文档最怕写成企业白皮书，一眼看过去全是“高效赋能、最佳实践、全链路能力”。

可以轻松一点，但别影响信息密度。

好的写法：

这里先别改全局样式，容易把暗色模式一起干碎。

不太好的写法：

本平台通过高度抽象的能力矩阵为用户提供先进体验。

看着就想关页面。

截图适合解释界面操作，但别滥用。

这个模板已经接了 remark-math 和 rehype-katex，可以写公式。

行内公式： $E = mc^2$

块级公式：

\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

写公式时，块级公式上下最好空一行。Markdown 解析器有时候脾气很怪，别给它机会发疯。

写完一页，至少检查这几件事：