跳到正文

列表与表格

用列表呈现操作和并列信息,用表格呈现可比较的字段,并在窄屏上检查可读性。

用编号表达顺序

操作有先后依赖时使用有序列表。每一步先给动作,再写所在位置或预期结果。同一步包含命令和结果时,把代码块放在该列表项内,使读者能对应动作和输出。附带检查项只需并列阅读时,使用无序列表。

1. 在项目根目录打开 `index.config.json`。
2. 将 `includeDrafts` 设为 `false` 并保存。
3. 重新生成索引,确认条目中没有草稿标题。

列表项保持同一种语法形式。例如,操作都以动词开头,条件都以“已……”之类的状态描述开头。完整句子保留句号,短语列表统一省略句号。嵌套的说明应与父项相关,层级变深时可以用小节承接。

让同一列回答同一个问题

需要比较多个选项的类型、默认值或适用场景时,用表格。列标题用读者要查找的概念,如“默认值”“适用版本”。单位相同的数字可在表头标记单位。字段含义长时,在表中保留简短定义,并用行内链接指向详细说明。

选项类型默认值触发条件
maxEntries整数100条目超过上限时只保留前 100 条
includeDrafts布尔值false设为 true 时收录草稿标题

空值有实际含义时,用“无默认值”“不适用”或“继承父项”区分。布局需要超过几列时,可以拆成多个表格,便于读者在手机上查看。

检查源文件和渲染结果

项目支持 GFM 管道表格时,用表头和分隔行声明表格。单元格中的竖线按渲染器规则转义。预览后检查表头和列是否对齐,长代码是否只在表格区域横向滚动。用键盘和触屏各滚动一次,确认能读到最后一列。