基本写作和格式语法

标题

要创建标题，请在标题文本之前添加一到六个 # 符号。使用的 # 数量将决定标题的层次级别和字体大小。

# A first-level heading
## A second-level heading
### A third-level heading

Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers, which descend in type size and visual weight to indicate descending hierarchy level.

当您使用两个或更多标题时，GitHub 会自动生成一个目录，您可以通过单击文件标题中的内容。每个标题标题都列在目录中，您可以单击标题以导航到所选部分。

Screenshot of the README file in the GitHub Docs open source repository with the drop-down menu for the table of contents exposed. The table of contents icon is outlined in dark orange.

文本样式

您可以在评论字段和 .md 文件中使用粗体、斜体、删除线、下标或上标文本来表示强调。

样式	语法	键盘快捷键	示例	输出
粗体	` ` 或 `__ __`	`Command`+`B` (Mac) 或 `Ctrl`+`B` (Windows/Linux)	`这是粗体文本`	这是粗体文本
斜体	`* *` 或 `_ _`	`Command`+`I` (Mac) 或 `Ctrl`+`I` (Windows/Linux)	`_这文本是斜体的_`	这文本是斜体的
删除线	`~~ ~~`	无	`~~这是错误的文本~~`	~~这是错误的文本~~
粗体和嵌套斜体	` ` 和 `_ _`	无	`这文本是_极其_重要的`	这文本是极其重要的
全粗体和斜体	`* *`	无	`*所有这文本都很重要*`	所有这文本都很重要
下标	`<sub> </sub>`	无	`这是一个<sub>下标</sub>文本`	这是一个_下标文本
上标	`<sup> </sup>`	无	`这是一个<sup>上标</sup>文本`	这是一个^上标文本

引用文本

你可以用 > 引用文本。

Text that is not a quote

> Text that is a quote

引用文本缩进，并以不同的颜色显示。

Screenshot of rendered GitHub Markdown showing sample quoted text. The quote is indented with a vertical line on the left, and its text is dark gray rather than black.

注意： 当查看对话时，你可以通过突出显示文本，然后输入 R 来自动引用评论中的文本。你可以通过点击，然后引用回复 来引用整个评论。有关键盘快捷键的更多信息，请参阅 "键盘快捷键。"。

引用代码

你可以在句子中用单反引号来引用代码或命令。反引号内的文本不会被格式化。你也可以按下 Command+E (Mac) 或 Ctrl+E (Windows/Linux) 键盘快捷键，在 Markdown 行中插入反引号以创建代码块。

Use `git status` to list all new or modified files that haven't yet been committed.

Screenshot of rendered GitHub Markdown showing the appearance of characters surrounded by backticks. The words "git status" appear in a fixed-width typeface, highlighted in light gray.

要将代码或文本格式化为独立的代码块，请使用三个反引号。

Some basic Git commands are:
```
git status
git add
git commit
```

Screenshot of rendered GitHub Markdown showing a code block. The words "git status," "git add," and "git commit" appear in a fixed-width typeface, highlighted in light gray.

有关更多信息，请参阅 "创建和突出显示代码块。"。

如果你经常编辑代码片段和表格，你可能需要在 GitHub 上的所有评论字段中启用等宽字体。有关更多信息，请参阅 "关于在 GitHub 上的写作和格式化。"。

支持的颜色模型

在问题、拉取请求和讨论中，您可以使用反引号在句子中调用颜色。反引号内的支持颜色模型将显示颜色的可视化效果。

The background color is `#ffffff` for light mode and `#000000` for dark mode.

Screenshot of rendered GitHub Markdown showing how HEX values within backticks create small circles of color. #ffffff shows a white circle, and #000000 shows a black circle.

以下是当前支持的颜色模型。

颜色	语法	示例
十六进制	`#RRGGBB`	`#0969DA`
RGB	`rgb(R,G,B)`	`rgb(9, 105, 218)`
HSL	`hsl(H,S,L)`	`hsl(212, 92%, 45%)`

注意

支持的颜色模型在反引号内不能有任何前导或尾随空格。
颜色的可视化仅在问题、拉取请求和讨论中受支持。

链接

您可以通过将链接文本括在方括号 [ ] 中，然后将 URL 括在圆括号 ( ) 中来创建内联链接。您也可以使用键盘快捷键 Command+K 来创建链接。当您选择文本时，您可以从剪贴板粘贴 URL 以自动从选择中创建链接。

您还可以通过突出显示文本并使用键盘快捷键 Command+V 来创建 Markdown 超链接。如果您想用链接替换文本，请使用键盘快捷键 Command+Shift+V。

此网站使用 [GitHub Pages](https://pages.github.com/) 构建。

Screenshot of rendered GitHub Markdown showing how text within brackets, "GitHub Pages," appears as a blue hyperlink.

注意：GitHub 在评论中写入有效 URL 时会自动创建链接。有关更多信息，请参阅 "自动链接的引用和 URL。"。

部分链接

您可以通过将鼠标悬停在部分标题上以显示来直接链接到渲染文件中的部分 .

Screenshot of a README for a repository. To the left of a section heading, a link icon is outlined in dark orange.

相对链接

您可以在渲染的文件中定义相对链接和图像路径，以帮助读者导航到存储库中的其他文件。

相对链接是相对于当前文件的链接。例如，如果您在存储库的根目录中有一个 README 文件，并且您在 docs/CONTRIBUTING.md 中有另一个文件，则您在 README 中指向 CONTRIBUTING.md 的相对链接可能如下所示

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHub 会根据您当前所在的任何分支自动转换您的相对链接或图像路径，以便链接或路径始终有效。链接的路径将相对于当前文件。以 / 开头的链接将相对于存储库根目录。您可以使用所有相对链接操作数，例如 ./ 和 ../。

您的链接文本应位于单行上。以下示例将不起作用。

[Contribution 
guidelines for this project](docs/CONTRIBUTING.md)

相对链接对于克隆存储库的用户来说更容易。绝对链接可能无法在您的存储库克隆中使用 - 我们建议使用相对链接来引用存储库中的其他文件。

图像

您可以通过添加 ! 并将 alt 文本用 [ ] 括起来来显示图像。alt 文本是图像中信息的简短文本等效项。然后，将图像的链接用括号 () 括起来。

![GitHub 问题评论的屏幕截图，显示了在 Markdown 中添加的 Octocat 微笑并举起触手的图像。](https://myoctocat.com/assets/images/base-octocat.svg)

Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.

GitHub 支持将图像嵌入到您的问题、拉取请求、讨论、评论和 .md 文件中。您可以显示来自您存储库的图像，添加指向在线图像的链接，或上传图像。有关更多信息，请参阅“上传资产”。

注意： 当您想要显示存储库中的图像时，请使用相对链接而不是绝对链接。

以下是一些使用相对链接显示图像的示例。

上下文	相对链接
在同一分支上的 `.md` 文件中	`/assets/images/electrocat.png`
在另一个分支上的 `.md` 文件中	`/../main/assets/images/electrocat.png`
在存储库的问题、拉取请求和评论中	`../blob/main/assets/images/electrocat.png?raw=true`
在另一个存储库的 `.md` 文件中	`/../../../../github/docs/blob/main/assets/images/electrocat.png`
在另一个存储库的问题、拉取请求和评论中	`../../../github/docs/blob/main/assets/images/electrocat.png?raw=true`

注意：上表中的最后两个相对链接仅当查看者对包含这些图像的私有存储库至少具有读取权限时，才能用于私有存储库中的图像。

有关更多信息，请参阅“相对链接”。

指定图像显示的主题

您可以使用 HTML <picture> 元素结合 prefers-color-scheme 媒体功能，在 Markdown 中指定图像显示的主题。我们区分浅色和深色颜色模式，因此有两个选项可用。您可以使用这些选项来显示针对深色或浅色背景优化的图像。这对于透明 PNG 图像特别有用。

例如，以下代码为浅色主题显示太阳图像，为深色主题显示月亮图像

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

根据主题指定图像的旧方法，即使用附加到 URL 的片段（#gh-dark-mode-only 或 #gh-light-mode-only），已弃用，并将被上述新方法取代。

列表

您可以通过在文本行前添加 -、* 或 + 来创建无序列表。

- George Washington
* John Adams
+ Thomas Jefferson

Screenshot of rendered GitHub Markdown showing a bulleted list of the names of the first three American presidents.

要对列表进行排序，请在每行前添加一个数字。

1. James Madison
2. James Monroe
3. John Quincy Adams

Screenshot of rendered GitHub Markdown showing a numbered list of the names of the fourth, fifth, and sixth American presidents.

嵌套列表

您可以通过将一个或多个列表项缩进到另一个项下方来创建嵌套列表。

要使用 GitHub 上的网页编辑器或使用等宽字体的文本编辑器（如 Visual Studio Code）创建嵌套列表，您可以通过视觉方式对齐列表。在嵌套列表项前面键入空格，直到列表标记字符（- 或 *）正好位于上面项中文本的第一个字符下方。

1. First list item
   - First nested list item
     - Second nested list item

注意：在基于 Web 的编辑器中，您可以通过先突出显示所需的文本行，然后分别使用 Tab 或 Shift+Tab 来缩进或取消缩进一行或多行文本。

Screenshot of Markdown in Visual Studio Code showing how indented bullets align vertically with the first letter of the text lines above them.

Screenshot of rendered GitHub Markdown showing a numbered item followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.

要在 GitHub 上的评论编辑器（不使用等宽字体）中创建嵌套列表，您可以查看嵌套列表正上方的列表项，并计算该项内容之前出现的字符数。然后，在嵌套列表项前面键入相同数量的空格。

在此示例中，您可以通过将嵌套列表项缩进至少五个空格来在列表项 100. First list item 下添加嵌套列表项，因为 First list item 之前有五个字符（100 .）。

100. First list item
     - First nested list item

Screenshot of rendered GitHub Markdown showing a list item prefaced by the number 100 followed by a bulleted item nested one level to the right.

您可以使用相同的方法创建多级嵌套列表。例如，因为第一个嵌套列表项在嵌套列表内容 First nested list item 之前有七个字符（␣␣␣␣␣-␣），所以您需要将第二个嵌套列表项缩进至少两个字符（至少九个空格）。

100. First list item
       - First nested list item
         - Second nested list item

Screenshot of rendered GitHub Markdown showing a list item prefaced by the number 100 followed by a bulleted item nested one level to the right, and another bulleted item nested yet further to the right.

有关更多示例，请参阅 GitHub Flavored Markdown 规范。

任务列表

要创建任务列表，请在列表项前添加一个连字符和空格，然后添加 [ ]。要将任务标记为已完成，请使用 [x]。

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] Add delight to the experience when all tasks are complete :tada:

Screenshot showing the rendered version of the markdown. The references to issues are rendered as issue titles.

如果任务列表项描述以括号开头，则需要使用 \ 对其进行转义。

- [ ] \(可选) 打开后续问题

有关更多信息，请参阅“关于任务列表”。

提及人员和团队

您可以在 GitHub 上通过输入 @ 加上他们的用户名或团队名称来提及某个人或团队。这将触发通知并引起他们的注意。如果您编辑评论以提及他们的用户名或团队名称，他们也会收到通知。有关通知的更多信息，请参阅“关于通知”。

注意： 只有当该人对仓库具有读取权限，并且如果仓库归组织所有，该人是该组织的成员时，该人才会收到提及通知。

@github/support 您对这些更新有什么看法？

Screenshot of rendered GitHub Markdown showing how the team mention "@github/support" renders as bold, clickable text.

当您提及父团队时，其子团队的成员也会收到通知，简化了与多个群体进行沟通。有关更多信息，请参阅“关于团队”。

输入 @ 符号将显示项目中的人员或团队列表。该列表会在您输入时进行过滤，因此，一旦找到您要查找的人员或团队的名称，您就可以使用箭头键选择它，然后按 Tab 键或 Enter 键完成该名称。对于团队，输入 @organization/team-name，该团队的所有成员都将订阅该对话。

自动完成结果仅限于仓库合作者和线程中的任何其他参与者。

引用问题和拉取请求

您可以通过输入 # 来显示仓库中建议的问题和拉取请求列表。输入问题或拉取请求编号或标题以过滤列表，然后按 Tab 键或 Enter 键完成突出显示的结果。

有关更多信息，请参阅“自动链接的引用和 URL”。

引用外部资源

如果为仓库配置了自定义自动链接引用，则对外部资源（如 JIRA 问题或 Zendesk 票证）的引用将转换为缩短的链接。要了解您的仓库中有哪些可用的自动链接，请联系仓库管理员权限的人员。有关更多信息，请参阅“配置自动链接以引用外部资源”。

上传资产

您可以通过拖放、从文件浏览器中选择或粘贴来上传图像等资产。您可以将资产上传到仓库中的问题、拉取请求、评论和.md文件。

使用表情符号

您可以通过键入:EMOJICODE:（冒号后跟表情符号的名称）将表情符号添加到您的写作中。

@octocat :+1: 这个 PR 看起来很棒 - 它已准备好合并！ :shipit

键入: 将显示一个建议的表情符号列表。该列表将在您键入时进行过滤，因此，一旦找到您要查找的表情符号，请按Tab或Enter键完成突出显示的结果。

有关可用表情符号和代码的完整列表，请参阅Emoji-Cheat-Sheet。

段落

您可以在文本行之间留一个空行来创建一个新段落。

脚注

您可以使用此方括号语法将脚注添加到您的内容中

Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
  This is a second line.

脚注将像这样呈现

Screenshot of rendered Markdown showing superscript numbers used to indicate footnotes, along with optional line breaks inside a note.

注意：脚注在 Markdown 中的位置不会影响脚注的呈现位置。您可以在脚注引用之后立即编写脚注，脚注仍将在 Markdown 的底部呈现。

维基不支持脚注。

警报

警报是基于块引用语法的 Markdown 扩展，您可以使用它来强调关键信息。在 GitHub 上，它们以独特的颜色和图标显示，以指示内容的重要性。

仅在警报对用户成功至关重要时才使用它们，并将它们限制为每篇文章一到两个，以防止读者超负荷。此外，您应该避免连续放置警报。警报不能嵌套在其他元素中。

要添加警报，请使用一个特殊的块引用行指定警报类型，然后在标准块引用中添加警报信息。有五种类型的警报可用

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

以下是呈现的警报

Screenshot of rendered Markdown alerts showing how Note, Tip, Important, Warning, and Caution render with different colored text and icons.

使用评论隐藏内容

您可以告诉 GitHub 从呈现的 Markdown 中隐藏内容，方法是将内容放在 HTML 注释中。

<!-- This content will not appear in the rendered Markdown -->

忽略 Markdown 格式

你可以通过在 Markdown 字符前使用 \ 来告诉 GitHub 忽略（或转义） Markdown 格式。

让我们将 \*our-new-project\* 重命名为 \*our-old-project\*。

Screenshot of rendered GitHub Markdown showing how backslashes prevent the conversion of asterisks to italics. The text reads, "Let's rename our-new-project to our-old-project."

有关反斜杠的更多信息，请参阅 Daring Fireball 的 "Markdown 语法。"。

注意：Markdown 格式不会在问题或拉取请求的标题中被忽略。

禁用 Markdown 渲染

查看 Markdown 文件时，你可以点击文件顶部的代码来禁用 Markdown 渲染，并查看文件的源代码。

禁用 Markdown 渲染使你能够使用源代码视图功能，例如行链接，这在查看渲染后的 Markdown 文件时是不可能的。