如何在 GitHub 和 Reddit 上快速使用 Markdown

信息技术数字 » 资源 » 如何在 GitHub 和 Reddit 上快速使用 Markdown

如果你经常在 GitHub 上写代码或者花很多时间浏览 Reddit，那么掌握Markdown绝对能帮你节省大量时间，让你的工作更轻松。它是一种非常轻量级的标记语言，只需在正确的位置放置几个符号，就能快速格式化纯文本，无需费力处理菜单或按钮。

在 GitHub 上，Markdown 无处不在：仓库的README.md文件、issue、pull request、讨论，甚至你的个人资料中都包含它。而 Reddit 则使用一种名为 Snoomark（Reddit 风格的 Markdown）的变体，它继承了 GitHub 的大部分语法，但也拥有一些独特的功能和限制。接下来，我们将通过大量的示例，一步一步地教你如何在 GitHub 和 Reddit 上快速高效地使用 Markdown，并且不会遗漏任何重要信息。

什么是 Markdown？为什么它在 GitHub 和 Reddit 上如此有用？

Markdown 是一种轻量级的标记语言，旨在让纯文本易于阅读和编写，同时还能轻松转换为 HTML。实际上，这意味着您可以编写普通文本，并添加一些特殊字符来创建标题、列表、表格、引用、格式化代码、链接或图像。

GitHub 使用的是 GitHub Flavored Markdown (GFM)，它在经典语法的基础上扩展了表格、待办事项列表、高级代码高亮、颜色支持、提示框以及一些允许使用的 HTML 标签。所有这些内容都会自动渲染到 .md 文件和平台的评论字段中。

Reddit 使用名为 Snoomark 的自有编辑器，它是 GFM 的衍生版本。它与 GFM 共享许多基本功能（粗体、斜体、标题、列表、引用、行内或块级代码、链接等），但也有一些重要的特点：例如，图像支持会根据上下文而有所不同，并且它还添加了自己的元素，例如剧透。

这一切的妙处在于，只需一套语法，你就能编写出在 GitHub 和 Reddit 上都美观的文本，只需针对两个平台不同的一些细节进行调整即可。掌握基本规则后，你就能轻松驾驭这两个平台，无需从头开始学习任何内容。

标题和内容结构

在 GitHub 和 Reddit 上，你最先会用到的功能之一就是标题。标题可以帮助你将文本组织成不同的章节和子章节。

在 Markdown 中，标题是通过在文本前面添加一到六个井号 (#) 来创建的：一个井号表示一级标题，两个井号表示二级标题，依此类推，直到六级标题。例如，在 GitHub 的 README.md 文件中，您可能会看到类似这样的内容：# 主标题，## 章节，### 子章节，等等。

当 GitHub 在一个文件中检测到两个或多个标题时，它会自动生成一个目录，您可以通过文件顶部的“大纲”图标访问该目录。每个标题都以链接的形式显示，点击即可直接跳转到相应部分，这对于长文档来说非常实用。

此外，每个标题都会成为一个内部锚点，您可以根据标题文本生成 URL 片段并链接到该锚点。为了生成该片段，GitHub 应用了非常具体的规则：它会将字母转换为小写，将空格替换为连字符，移除标点符号和格式字符（例如斜体），去除多余的空格，并且，如果结果与之前的另一个标题匹配，则会添加一个数字后缀（-1、-2 等）以使其唯一。

这样，你就可以执行诸如放置一个## 示例章节，然后从文档中的其他位置使用类似(#sample-section)的链接链接到它，甚至可以链接到标题中包含特殊字符的章节，因为 GitHub 会按照这些规则生成代码片段，并使其以相同的模式可访问。

强调、高亮文本和引文

Markdown 允许您使用各种强调方式来突出显示文本：粗体、斜体、删除线、下标、上标或下划线。在 GitHub 上，典型的样式表如下所示，不过我们在这里用不同的方式对其进行了概括：

要使文本加粗，请在文本两侧加上双星号或双下划线；要使文本斜体，请使用单星号或单下划线；要添加删除线，请在文本两侧各加一个波浪号（两个波浪线）。您还可以组合使用粗体和斜体，使用三个星号将粗体和斜体应用于整段文本，或者使用 HTML 标签，例如 `<b>`_{用于^{下标和上标，`<i>`用于下划线。}}

GitHub 还允许您通过在行首添加大于号 (>)来创建引用块。引用的文本会以灰色竖线显示在左侧，使其清晰可见。您可以在同一个引用块中包含多行，甚至可以通过在开头添加更多 > 符号来嵌套引用。

GitHub 特有的高级引用形式是警告或提示。它使用相同的引用块语法，但第一行包含一个特殊标记来指示警告类型。例如，您可以指定 `alert` 表示有用信息，`helpful tips` 表示实用技巧，`key data` 表示关键数据，`urgent warnings` 表示紧急警告，`warnings of risks or negative consequences` 表示风险或负面后果警告。GitHub 会用不同的颜色和图标显示每种类型，帮助您突出显示文档中的关键信息。

Reddit 也支持使用 > 符号进行简单引用，尽管它不像 GitHub 那样拥有丰富的 ping 系统。即便如此，它仍然是一种非常实用的回复方式，可以引用对方消息的一部分，而无需重复整条消息。

代码高亮、代码块和颜色

GitHub 和 Reddit 都允许你使用反引号高亮显示文本中的代码片段。对于行内代码，你需要在单词或命令的两侧各加一个反引号。这非常适合高亮显示例如句子中的 ` git status`，从而清晰地表明这是一个命令。

当您需要一段独立的代码块时，Markdown 使用三个反引号：您用三个反引号开始一行，然后在单独的行中编写代码，最后再用三个反引号结束。在 GitHub 上，如果您在第一个反引号后指定语言，则会应用该语言特有的语法高亮和格式。

GitHub 还提供了一个专门用于高亮反引号内颜色值的功能。如果您在反引号内输入十六进制、RGB 或 HSL 格式的颜色值，平台会在文本旁边显示一个小的颜色指示器。例如，如果浅色模式下的背景色是 #ffffff，深色模式下的背景色是 #000000，高亮显示这些代码可以让您快速区分哪个是哪个。

关于代码和表格显示，GitHub 允许您在所有注释字段中启用等宽字体，从而更轻松地处理技术文本。如果您经常在浏览器或Visual Studio Code等编辑器中编辑代码片段，启用此选项将使对齐方式和可读性更加一致。

Reddit 也支持使用反引号的代码块，包括行内代码块和块级代码块，尽管它们在那里更多地用于小的代码片段或伪代码，而不是像存储库那样的长篇文档。

链接、锚点和内部导航

在 Markdown 中创建链接非常简单：只需将要显示给用户的文本放在方括号中，将 URL 放在圆括号中即可。这种方法在 GitHub 和 Reddit 上都适用，并且在 GitHub 上还可以通过键盘快捷键进行增强（例如，使用组合键快速将选定的文本转换为链接）。

GitHub 添加了一些与导航相关的额外功能。首先，它允许你使用前面讨论过的代码片段生成规则直接链接到标题。其次，它支持仓库内部的相对链接，这对于技术文档至关重要。

相对链接是指以当前文件为参照计算的链接。例如，如果您的 README 文件位于项目根目录，而您想要链接到 docs/CONTRIBUTING.md 文件，您只需编写一个路径为 docs/CONTRIBUTING.md 的链接即可。GitHub 会在您当前所在的任何分支中正确转换此相对链接，从而防止在切换分支或克隆仓库时链接失效。

建议在同一仓库的文件之间导航时始终使用相对路径，因为绝对链接在克隆或派生的仓库中可能会失效。GitHub 允许使用诸如 `./` 或 `../` 之类的标准运算符，以及相对于项目根目录的以 `/` 开头的路径。

如果想在文档中创建标题以外的自定义锚点，可以使用带有 `name` 属性的 HTML 标签。这样，您可以将目标点放置在段落中间或没有标题的文本旁边，并使用与自动生成的标题相同的语法链接到该锚点。

GitHub 上的图片：Markdown、HTML 和相对路径

在 GitHub 上，图片通常使用与链接相同的语法嵌入，但前面要加一个感叹号。替代文本（alt）放在方括号内，图片的 URL 或路径放在圆括号内。替代文本对于可访问性至关重要，因为屏幕阅读器会读取它，并且在图片加载失败时会显示它。

图片可以来自仓库内部的文件，也可以来自外部 URL。GitHub 支持多种相对路径模式，用于从不同的分支、其他仓库，甚至是 issue 和评论中上传图片，并可使用类似`?raw=true` 的后缀在必要时强制直接下载文件。

除了标准的 Markdown 语法外，GitHub 还支持使用 HTML 的 `<picture>` 元素。该元素对于加载响应式图片尤为有用，这些图片会根据用户的主题偏好（浅色或深色）而变化。使用 `prefers-color-scheme` 媒体查询，您可以为每种模式定义不同的图片源，并为不支持此功能的浏览器设置默认图片。

典型模式包括包含在内几个要素及其媒体和 srcset 属性，最后是一个使用 alt 属性和通用 URL，深色模式下的用户可以看到调整后的图像，而浅色模式下的用户可以看到不同的图像，而无需在 README 文件中重复内容。

GitHub 还支持 Markdown 文件中的 HTML 注释，允许您向读者添加不可见的提醒，例如提醒他们稍后更新图像部分或添加新示例。

表格、折叠页和内容分隔

GitHub Flavored Markdown 最实用的改进之一就是它对表格的支持。你可以使用竖线分隔单元格，用一行短横线标记表头，将数据组织成行和列。此外，你还可以使用分隔符中的冒号将列右对齐、左对齐或居中对齐。

表格非常适合用来展示编程语言列表、使用的框架、计划任务、功能对比，或者任何其他适合矩阵结构的信息。GitHub 以简洁易读的样式呈现这些表格。

为了使篇幅较长的 README 文件保持条理清晰，您可以使用 HTML 标签 `<details>` 创建可折叠的章节。这些章节会在 `<summary>` 标签内显示摘要，并允许用户根据需要展开或折叠其他内容。通常的做法是将表格或辅助信息块放在 `<details>` 标签内，以避免用户第一眼看到过多信息而感到不知所措。

如果您希望该部分默认展开显示，只需添加 open 属性即可。这种方法非常适用于对排名、长列表或对于初次阅读来说并非必不可少但便于访问的内容进行分组。

另一种简单的整理信息的工具是水平线。它由三条或更多短横线组成，用于划分各个部分，例如，可以清晰地将描述性部分与参考文献或补充说明部分分开。

这些规则可以与文档末尾引用结合使用，以突出显示励志短语、提醒事项或关键信息。一个典型的例子是在个人资料 README 文件的末尾放置一句励志名言，并以分隔符后插入一段引用文本。

隐藏注释和格式控制

GitHub 允许你使用语法 <!-- 注释 --> 在 Markdown 中插入HTML 注释。注释中的任何内容都不会显示在渲染后的内容中，但会在源代码中可见，因此非常适合用于内部笔记或待办事项。

例如，在个人资料的 README 文件中，您可以添加一条评论，说明您需要稍后扩展“关于我”部分，或者您需要查看过时技术表，而无需让访问该个人资料的任何人直接看到它。

另一个实用功能是转义通常会被解释为 Markdown 的字符。如果您需要直接显示星号、井号或其他符号而不进行格式化，只需在每个符号前加上反斜杠即可。例如，这样您就可以编写包含列表符号的表达式，而无需将其转换为实际的列表。

在 GitHub 上查看标记文件时，您可以通过顶部的按钮在渲染视图和源代码之间切换（或者在Brackets等编辑器中打开）。禁用 Markdown 解析后，您可以访问典型的代码视图功能，例如链接特定行，这在您想要突出显示 README 或任何 .md 文件的特定部分时非常有用。

最后，请记住 GitHub 对评论（issue、PR 等）和 .md 文件中的换行符处理方式不同。在评论中，换行符会被直接保留；而在 Markdown 文件中，您需要在行尾添加两个空格、一个反斜杠或一个句点。强制在同一段落内跳转。

列表、嵌套列表和待办事项列表

列表是 Markdown 中最常用的元素之一，无论是在 GitHub 还是 Reddit 上都是如此。您可以通过在每个列表项前添加连字符、星号或加号来创建无序列表。所有这些标记的渲染效果都类似于项目符号。

要生成有序列表，请用数字、句点和空格对每一行进行编号。虽然数字顺序不必完全一致（GitHub 通常会重新计算），但为了保持源代码的可读性，最好保持一致的编号。

创建嵌套列表只需缩进其下方的列表项即可。在Sublime Text等等宽字体编辑器中，只需将嵌套列表标记在视觉上与父级列表项文本的第一个字符对齐即可。在 GitHub 评论编辑器等非等宽字体环境中，则需要计算文本前面有多少个字符，并使用相应数量的空格进行缩进。

只要保持空格数量一致，你还可以构建多层嵌套。对于非常复杂的列表，这种方法需要一些练习，但一旦掌握了技巧，应用起来就非常快捷。

GitHub 还提供了任务列表功能，这对于问题、拉取请求和文档​​编写都非常有用。创建任务列表的方法是：在列表名称前加上一个连字符、一个空格，以及一对方括号（方括号内可以有一个空格或一个“x”），一个方括号用于表示待处理的任务，另一个方括号用于表示已完成的任务。这些列表会以复选框的形式呈现，用户可以在界面中选中或取消选中它们。

如果待办事项列表项的文本以括号开头，则必须使用反斜杠进行转义，以避免解析器出现混淆。这是一个小细节，但在编写以“（可选）”或类似内容开头的描述时非常重要。

GitHub 上的提及、引用和表情符号

在 GitHub 上使用 Markdown 编写代码的优势之一是可以直接提及平台上的用户和团队。只需输入 @ 符号，后跟用户名或团队名称，GitHub 就会向该帐户发送通知，吸引他们关注对话。

输入 @ 符号后，GitHub 会显示与该仓库或主题关联的用户和团队列表，您可以在输入时筛选此列表。使用方向键并按 Enter 或 Tab 键接受建议。对于团队，请使用 @组织/团队名称 的格式，所有团队成员都将订阅该主题。

除了提及功能外，GitHub 还提供了便捷的引用 issue 和 pull request 的方式，只需输入 # 后跟数字或部分标题即可。系统会显示建议结果列表，您可以像引用一样填写列表内容。这极大地加快了在相关对话之间切换的速度。

如果您的代码库配置了自定义自动链接引用，某些外部标记（例如 JIRA 或 Zendesk 工单 ID）也可能自动转换为短链接。此设置需要管理员权限，但启用后，即可轻松实现跨系统数据共享。

最后，GitHub 支持通过代码输入表情符号：输入一个冒号，后跟表情符号名称，再以另一个冒号结尾。开始输入时，会出现一个建议列表，您可以按 Tab 键或 Enter 键接受建议。在评论中加入表情符号有助于使其更具人情味，但请注意不要在正式文档中过度使用。

脚注和高级内容

GitHub 也支持使用基于方括号的语法和带插入符号的标识符来添加脚注。在需要引用的地方，插入类似 `<footnote>` 的标签；在文档末尾，使用相同的标签定义脚注文本，后跟冒号和正文内容。

脚注可以跨越多行，要在脚注内强制换行，只需在行尾使用双空格，就像 Markdown 正文一样。渲染时，GitHub 会在文本上方显示上标，并在文末显示脚注列表，其中包含用于在参考文献和脚注之间跳转的反向链接。

GitHub 提供的另一项高级功能是前面提到的提示信息（注意、提示、重要、警告和警告）。建议仅在真正必要时使用它们，并避免过多组合使用，以免信息过载。这些提示信息不能嵌套在其他复杂元素中，因此仔细规划它们的放置位置至关重要。

最后，你可以让 GitHub 暂时隐藏已渲染的 Markdown 代码片段（例如用 HTML 注释包裹），或者忽略某些包含反斜杠的字符。这在编写Markdown 语法文档并需要直接展示示例而不加解释时尤其有用。

Reddit 上的 Markdown：Snoomark 和编辑模式

Reddit 是一个讨论平台，几乎任何话题都欢迎，并以子版块的形式组织起来。在格式方面，它提供了两种编辑器：一种用于更直观的富文本编辑器，另一种用于基于 Markdown 的纯文本编辑器。如果您想要快速编辑并精细控制最终效果，建议您使用 Markdown 编辑器。

Reddit 默认启用富文本编辑器，因此要切换到标记语言模式，您需要在帖子或评论的文本框中点击Markdown 模式选项。之后，您就可以直接使用 Snoomark 语法了。

如果您希望始终加载 Markdown 编辑器，请前往用户设置，进入“Feed 设置”部分，并启用“默认使用 Markdown”选项。这样，每次您开始撰写文章或评论时，Markdown 编辑器都会自动打开，无需您手动更改。

Reddit 支持大多数基础和高级 Markdown 功能：标题、粗体和斜体、列表、引用、代码块、链接，以及一些自身特有的额外功能，例如剧透。然而，与 GitHub 相比，它存在一些明显的不足，尤其是在图像处理方面，图像处理高度依赖于上下文和编辑器类型。

Reddit支持的语法和剧透

Reddit 使用的 Snoomark 变体与 GitHub 有许多共同之处，因此，如果您已经熟练掌握 Markdown 代码仓库的使用，那么将这些知识迁移到 Reddit 环境就非常简单。您可以使用标题来组织长篇帖子，使用编号或项目符号列表，使用引用来回复其他用户，以及使用代码块来显示命令或技术代码片段。

其中一个显著区别在于Reddit处理图片的方式。虽然很多情况下图片是通过图形界面上传的，而不是直接使用Markdown语法，但处理文本内容的引擎仍然是Snoomark，因此这些图片的格式实际上是基于Markdown的。

另一方面，Reddit 添加了一些标准规范中未包含的额外功能，例如剧透。剧透功能允许将文本隐藏在一个图层后面，用户可以通过点击图层来显示该图层。从技术上讲，当 Reddit 处理剧透内容时，它会将其转换为 HTML、CSS 类和平台特定的 JavaScript 代码的组合。

剧透内容的 HTML 表示形式包含控制何时显示或隐藏内容的处理程序。虽然理论上可以用纯 HTML 编写类似的功能，但在 Reddit 上，这取决于其内部实现。作为用户，重要的是，在编写时，您只需使用编辑器提供的特定剧透语法，Snoomark 会自动将其转换为相应的结构。

简而言之，Snoomark 继承了 GitHub Flavored Markdown 的许多特性，但它更侧重于满足讨论社区的需求，而非项目文档。即便如此，其核心仍然相同：将包含简单符号的纯文本转换为结构化且易于阅读的内容。

掌握 GitHub 和 Reddit 上的 Markdown 语法，能显著提升编写技术文档、创建条理清晰的问题、在 pull request 中留下明确评论以及参与 Reddit 讨论的效率。只需掌握一些关键规则——标题、强调、列表、引用、代码块、链接、图片，以及一些实用技巧，例如表格、可折叠详情、警告框、脚注和剧透——你就能从撰写平淡无奇的信息，转变为创建简洁、易读且专业的文本内容，而无需点击任何鼠标按钮。