格式指南

Table of contents

标题和子标题

读者会略微多关注标题、项目符号列表和链接，因此确保这些项目的前两到三个词尽可能地“前置加载”信息非常重要。

页面标题应以行动为导向。例如：

图像，包括屏幕截图，可以帮助读者更好地理解概念。然而，应谨慎使用它们，因为它们容易过时。

有关如何将图像添加到内容的信息，请参阅有用的组件和格式示例。

注意不要创建太多链接，尤其是在正文文本中。过多的链接会分散注意力，或将读者从当前页面引开。

当人们点击链接时，他们通常会忘记自己的思路，并且尽管没有吸收页面上的所有信息，也可能无法返回原始页面。

最好的链接为读者提供了另一种扫描信息的方式。

有关如何向内容添加链接的信息，请参阅有用的组件和格式示例。

将以下内容格式化为代码：Docker 命令、指令和文件名（包名）。

要应用内联代码样式，请将文本用单个反引号 (`) 括起来。

有关如何向内容添加代码块的信息，请参阅有用的组件和格式示例。

命令提示符和 shell：
- 对于非特权 shell，在代码块中的命令前加上 $ 提示符。
- 对于特权 shell，在代码块中的命令前加上 # 提示符。
- 对于远程 shell，添加远程计算机的上下文并排除路径。例如，user@host $。
- 添加任何特定于 Windows 的命令时，请指定 Windows shell（命令提示符、PowerShell 或 Git Bash）。无需为每个 Windows shell 都包含命令。
- 当您为多个操作系统或 shell 添加命令时，请使用选项卡。有关如何向内容添加选项卡的信息，请参阅选项卡。
用户将复制并运行的命令：
- 如果命令产生输出或需要用户验证结果，请为每个命令添加一个代码块。
- 将命令输出与命令分开添加到单独的代码块中。
用户不会复制和运行的命令：
- 使用 POSIX 兼容语法。无需包含 Windows 语法。
- 将可选参数用方括号 ( [ ] ) 括起来。
- 在互斥参数之间使用管道 ( | )。
- 在重复参数后使用三个点 ( ... )。

使用提示框来强调页面上的选定信息。

文本提示框	使用场景	颜色或提示框类型
Warning	使用 Warning 标签向读者发出警告，指出某些操作可能导致硬件损坏或数据丢失。	红色
	✅ 示例：Warning: 当您使用 `docker login` 命令时，您的凭据会存储在您主目录的 `.docker/config.json` 文件中。密码在该文件中以 base64 编码。
Important	使用 Important 标签向读者指出某些操作可能导致较低严重性的问题。	黄色
	✅ 示例：更新 Docker Desktop 条款
Note	使用 Note 标签提供可能不适用于所有读者的信息，或与主题相关性不大的信息。	蓝色
	✅ 示例：删除仓库会删除其包含的所有镜像及其构建设置。此操作无法撤销。

有关如何向内容添加提示框的信息，请参阅有用的组件和格式示例。

始终先使用位置，然后是操作。例如： 从 可见性 下拉列表（位置）中，选择 Public（操作）。
简洁且具体。例如：正确做法：选择保存。 错误做法：选择保存以使更改生效。
如果某个步骤必须包含原因，请以该原因开始步骤。这有助于用户更快地浏览。正确做法：要查看更改，请在合并请求中选择链接。 错误做法：在合并请求中选择链接以查看更改。