代码块与行内代码
给围栏代码块注明语言,例如 bash、ts 或 json。行内出现的命令、文件名、参数、环境变量和字面量用反引号包起来。命令与输出分别放进代码块,读者可以直接复制命令。
例如,在仓库根目录执行以下命令可以构建站点。
pnpm run build
构建完成后,检查项目根目录下生成的 .output/。
让示例可以复现
在示例前标明运行位置、依赖版本和必要配置。示例使用最小输入,保留能解释行为的调用。使用示例域名和占位值,并说明哪些值需要替换。注释说明意图、单位或边界条件。
只有片段时,说明要放入哪个文件、替换哪一段。引用输出时,保留读者需要核对的字段,并标明输出会随环境而变化的部分。
按代码的用途选择展示方式
| 代码的用途 | 写法 |
|---|---|
| 在终端执行的命令 | 注明运行目录,使用纯命令块 |
| 要放入文件的片段 | 标注文件名和放置位置,说明依赖的导入 |
| 状态或输出 | 单独展示输出,说明其中会变化的值 |
| 可互换的平台命令 | 按代码组语法或分段组织 |
同一组示例用一致的变量、路径和配置值。验证时从预览页复制,在声明的环境运行一次,并对照成功输出与一个边界输入。完整的可执行示例可参考实用配方。
记录 API 行为
先给出调用签名和用途,再说明参数、返回值和错误。每个参数说明类型、是否必填、默认值、单位和有效范围中适用的字段。已有默认值示例时,核对代码是否实际使用了该默认值。
描述错误时,写清触发条件和可观察的错误码或消息。复杂对象适合用表格或独立小节记录字段。最后给出至少一个能体现典型行为的调用。
按条目类型使用更具体的函数与 HTTP API 参考、配置项参考或命令行参考。