按读者需要选择形态
| 内容 | 表达方式 | 放置位置 |
|---|---|---|
| 完成操作必须满足的条件 | 前置条件或步骤正文 | 操作前 |
| 有助于理解的默认行为 | 说明 | 第一次使用该默认值的位置 |
| 可选的省时做法 | 提示 | 读者完成主路径后 |
| 容易导致失败的限制 | 警告 | 受影响的步骤前 |
| 可能不可逆的后果 | 重要警示并给出备份或验证动作 | 执行前、靠近具体操作 |
提示应回答影响对象、触发条件和读者能采取的动作。用“旧索引会在重新生成时被覆盖。需要保留旧结果时,先复制输出文件”交代后果和处理方法,比“请务必小心操作”更具体。
在步骤正文中交代关键条件
只有在备份通过验证后才能继续的操作,应在流程步骤中明确安排备份和检查。提示框可以补充原因。条件有分支时,先说明谁会受到影响,再提供各自的操作,从而支持读者在提交配置或启动任务前判断。
在文档站预览提示框
本指南使用 Nuxt UI 的提示组件渲染 Markdown 中的 note、tip、warning 和 caution。可在文档组件说明中查看语法。迁移到其他渲染器时,确认文字、链接和提示级别都能被正确呈现。
使用独立的输出目录可以保留上一次构建的索引。生成后核对实际输出路径。
提示类型应能从文字判断。标题或首句直接交代后果,颜色和图标用于辅助识别。