如何为 .md markdown 中的操作说明添加注释或备注？

2026-11-04技术老齐

在 Markdown 操作说明中，可以直接把读者可见的备注写在对应步骤后。备注可以用普通段落，也可以用 > 引用块突出显示，参考资料则以 Markdown 链接的形式附在说明中。

Markdown 没有给某一行附加可见注释的通用语法。通常可以把备注紧接着写在步骤后，或通过列表缩进、脚注标记说明它对应哪一步。

在步骤下方添加备注

以更新软件包索引为例：

1. 更新软件包索引：

   ```sh
   sudo apt-get update
   ```

   > 备注：此命令用于更新本地软件包索引，方便后续安装时获取软件包信息。
   > 相关资料可从 [Ubuntu 文档](https://documentation.ubuntu.com/)查阅。

将代码块和备注都缩进到列表项内，渲染后它们就会归属于同一个步骤。> 是引用块语法，“备注：”是自行添加的文字。

不需要突出显示时，可以改用普通段落：

```sh
sudo apt-get update
```

备注：此命令用于更新本地软件包索引。

步骤是否可选、建议执行的理由，都应根据实际安装要求填写。不能仅凭示例中的链接，就认定文档推荐了这项操作。正式发布时，最好链接到解释该操作的具体文档页面。

给指定句子补充说明

要给某一行补充说明，可以在它后面添加备注：

to comment/disable anything inside

> 备注：这里指的是让内容不出现在渲染后的页面中，可以使用 HTML 注释。
> 注释内容仍然保留在 `.md` 源文件中。

简短的说明也可以直接放在句末：

使用 HTML 注释隐藏内容（备注：内容仍保留在 `.md` 源文件中）。

HTML 注释  用于隐藏内容。需要让读者看到的解释，应写在注释标记之外。

说明较长时使用脚注

如果发布平台支持脚注，可以在需要解释的位置添加标记，把详细说明放在后面：

使用 HTML 注释隐藏内容。[^html-comment]

[^html-comment]: 注释内容不会显示在渲染后的页面中，但仍可在 `.md` 源文件中查看。

脚注属于扩展语法，并非所有 Markdown 渲染器都支持。发布前应在目标平台预览。兼容性不确定时，用普通段落或引用块更稳妥。

编写时的注意事项

# 在 Markdown 正文行首通常表示标题，不能像 Shell 中那样用来添加注释。
备注应放在代码块外，才能作为正文排版；放在代码块内会按代码显示。
正文与备注块之间保留空行，列表内的备注保持正确缩进，避免被解析为其他内容。
读者必须在操作前了解的条件或风险，应写在步骤前，避免执行后才看到说明。