跳到正文

标题、段落与目录

用可扫描的标题和明确的段落组织页面,让读者通过目录和搜索直接找到答案。

用读者会查询的词写标题

页面标题说清任务或对象,正文标题反映该段实际内容。操作标题使用“生成搜索索引”这样的动宾短语,参考标题使用“默认值”或“返回值”这样的对象名。多处同名时补上对象,例如“缓存默认值”,避免目录中出现难以区分的重复入口。

原标题改写适用位置
开始安装索引工具首次安装章节
一些说明索引更新时机概念说明
注意事项验证输出目录执行和检查步骤

建立连续的标题层级

本指南以 frontmatter 的 title 作为一级标题。正文从 ## 开始,同一主题下使用 ### 拆分。需要中文标题锚点时,从实际预览页取地址,并遵循链接与锚点的验证步骤。标点保留在正文,标题用足以分辨的小短语。

用三级标题分解一个主题

例如,“检查构建结果”下可以安排“确认文件位置”和“运行一次搜索”两个三级标题。如果读者开头就需要做选择,可让分支共享一个二级标题,并在第一段写清选择条件。

用段落推进一个问题

开头先写当前段落负责的结论、操作或条件,再补原因和例子。相邻段落要能说明各自负责的内容。一个段落里出现多个互不依赖的操作时,考虑拆成列表或小节。

读者常从搜索直接进入某个小节。需要使用变量、术语或文件时,在该小节交代其全名或用行内链接指向定义。预览目录后确认能通过标题找到条件、动作和结果。