用 Notion 标题层级设计技术文档的架构-夜雨聆风

用 Notion 标题层级设计技术文档的架构

写技术文档最怕什么？不是写不出来，而是写完之后自己都看不懂。层级混乱、结构松散，找个信息翻半天。今天咱们就聊聊怎么用 Notion 的标题层级，把技术文档的骨架搭得清清楚楚。

一、先搞懂 Notion 的三级标题

Notion 里的标题分三级：H1、H2、H3，对应输入 /heading 1、/heading 2、/heading 3，也可以直接用快捷键 Cmd/Ctrl + Shift + 1/2/3 快速切换。

简单理解：

举个例子，你写一份 API 接口文档：

H1：用户模块（大方向）　H2：登录接口（具体接口）　　H3：请求参数 / 返回示例 / 错误码（细节说明）

这样一层套一层，读的人一眼就能抓到重点。

标题搭好之后，别忘了在文档顶部加一个目录块（Table of Contents）。输入 /toc 就能生成，它会自动抓取页面里所有标题，生成可点击跳转的导航栏。

🏆 达人经验：技术文档超过 800 字就一定要加目录块。另外，把目录放在一个 Callout 区块里，视觉上更醒目，阅读体验直接拉满。

原则一：H1 不超过 5 个。 一篇文档大章节太多，说明你该拆成多个页面（Page）了。Notion 支持页面嵌套，善用”子页面”比硬塞在一个页面里强得多。

原则二：层级严格递进，别跳级。 H1 下面直接跟 H3，读起来会让人懵。就像你写大纲不会从”第一章”直接蹦到”1.1.1″一样。

原则三：标题要能独立表意。 别写”说明””备注”这种模糊标题，改成”接口鉴权说明””超时重试备注”，扫一眼就知道讲什么。

🏆 达人经验：给团队写文档模板（Template）时，把标题层级预设好，同事直接往里填内容就行，省去反复对齐格式的麻烦。在数据库里建一个”技术文档模板”，新建页面时一键套用，效率翻倍。

技术文档里经常有大段代码或参数表，全部展开会让页面又长又压迫。这时候用 切换器（Toggle） 把细节折叠起来，标题层级负责骨架，切换器负责收纳血肉，主次分明。

比如 H3 标题”请求参数”下面，用一个 Toggle 把参数表格包起来，需要的人点开看，不需要的人直接跳过。