在 GitHub Docs 中使用 Markdown 与 Liquid

您可以使用 Markdown 和 Liquid 来格式化内容、创建可重用内容，并为不同版本的 GitHub Docs 编写内容。

本文内容

关于在 GitHub Docs 中使用 Markdown 与 Liquid

GitHub Docs 使用 Markdown 编写，Markdown 是一种对人类友好的纯文本格式语法。我们使用称为 GitHub Flavored Markdown 的 Markdown 变体，并确保其符合 CommonMark。欲了解更多信息，请参阅 关于在 GitHub 上编写和格式化的说明。

我们使用 Liquid 语法来扩展功能，以提供可访问的表格、可维护的链接、版本控制、变量以及可重用内容块。有关 Liquid 的更多信息，请参阅 Liquid 文档。

本站点的内容使用由 /src/content-render 提供动力的 Markdown 渲染，该渲染基于 remark Markdown 处理器。

列表

在列表项中，首段之后的附加内容的一般规则如下：

  • 图像和随后出现的段落每个都应单独占一行，并且之间需留一个空行。
  • 列表项中的所有后续行必须与列表标记后面的首段文本对齐。

列表的示例用法

此示例展示了在具有多个段落或对象的列表项中正确对齐的方式。

1. Under your repository name, click **Actions**.

   ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab-global-nav-update.png)

   This is another paragraph in the list.

1. This is the next item.

此内容在 GitHub Docs 网站上显示时，第一项列表下的内容已正确对齐。

在 GitHub Docs 上渲染的示例列表

  1. 在仓库名称下方，点击 Actions。

    Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.

    这是列表中的另一段落。

  2. 这是下一个项目。

警报

警报用于突出显示用户需要了解的重要信息。有关受支持的警报类型、在 Markdown 中如何格式化它们以及何时使用警报的详细信息，请参阅 样式指南。

警报示例

> [!TIP]
> Try this out!

> [!NOTE]
> Generally alerts should be short.
>
> But occasionally may require more than one paragraph

在 GitHub Docs 上渲染的示例警报

提示

试一试！

注意

通常警报应简短。

但有时可能需要超过一个段落。

代码示例语法高亮

要在命令行指令和代码示例中渲染语法高亮，我们使用三个反引号并在其后添加示例的语言。有关所有受支持语言的列表，请参阅 code-languages.yml。

代码语法高亮的示例用法

```bash
git init YOUR-REPOSITORY
```

在代码示例语法中，使用全大写文本来表示占位符文本或因用户而异的内容，例如用户名或仓库名。默认情况下，代码块会转义三重反引号之间的内容。如果需要编写会解析内容的示例代码（例如，将 <em> 标签的文本斜体化而不是字面传递标签），请将代码块包裹在 <pre> 标签中。

带复制按钮的代码块

您还可以添加一个标题，其中包括语言名称以及用于复制代码块内容的按钮。

例如，以下代码为 JavaScript 添加了语法高亮并在代码示例旁提供了复制按钮。

复制按钮的示例用法

```javascript copy
const copyMe = true
```

在 GitHub Docs 上渲染的示例代码

JavaScript
const copyMe = true

代码示例注释

代码示例注释通过在示例代码旁渲染注释来帮助解释较长的代码示例。这样我们可以在不使代码本身混乱的情况下，对代码进行更长的说明。带注释的代码示例采用双窗格布局，左侧显示代码示例，右侧显示注释。当有人将光标悬停在代码示例上时，注释会被视觉强化。

代码注释仅在具有 layout: inline frontmatter 属性的文章中有效。有关如何编写和样式化代码注释的更多信息，请参阅 为代码示例添加注释。

带注释的代码示例示例

```yaml annotate
# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute the [`gh pr comment`](https://cli.github.com/manual/gh_pr_comment) command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $
```

有关在 GitHub Docs 中使用代码注释的文章示例，请参阅 使用 GitHub Actions 发布和安装软件包。

Copilot 提示

Copilot 的提示可以以块的形式显示，也可以内嵌在文本中。

提示块

这些块非常类似于代码块，但使用 copilot 关键字，而不是编程语言的名称。

提示块应始终带有复制按钮，可通过 copy 选项添加；也可以通过 prompt 选项添加 Copilot 按钮。Copilot 按钮为读者提供在 GitHub.com 上的 Copilot Chat 中快速运行提示的方式。copy 和 prompt 选项的顺序可以随意。

带 Copilot 和复制按钮的示例提示块

```copilot prompt copy
What is git?
```

它的渲染结果如下：

Copilot 提示
What is git?

只有在以下情况下才应在提示块中添加 Copilot 按钮：

  • 提示可以在不需要任何进一步上下文的情况下运行（如上例所示）。
  • 同篇文章中有一个代码块提供了提示所需的上下文。

为提示添加上下文

如果使用 Copilot 按钮，可以通过在同篇文章中引用代码块来为发送给 Copilot Chat 的提示添加上下文。操作方式是为代码块添加 id=YOUR-CHOSEN-STRING，并在提示块中添加 ref=YOUR-CHOSEN-STRING。

在提示块中用作上下文的示例代码块

Add an id to the code block whose code you want to add to the prompt as context:

```javascript id=js-age
function logPersonsAge(a, b, c) {
  if (c) {
    console.log(a + " is " + b + " years old.");
  } else {
    console.log(a + " does not want to reveal their age.");
  }
}
```

Then, elsewhere in the same article, reference the id in the prompt block:

```copilot copy prompt ref=js-age
Improve the variable names in this function
```

Copilot Cookbook 中有许多带上下文的提示块示例。例如，请参阅 改进代码可读性和可维护性。

内联提示

对于大多数内联提示，请使用反引号标记它们，就像内联代码一样。

如果提示不需要任何上下文，您可以在提示后添加可点击的 Copilot 图标。这样读者即可在 GitHub.com 的 Copilot Chat 中运行提示。要添加可点击的图标，请使用 Liquid 语法标签将提示包裹起来。

... you can click {% prompt %}what is git{% endprompt %} to run this ...

它的渲染结果如下：

... 您可以点击 what is git 来运行此 …

Octicons 图标

Octicons 是在 GitHub 界面中使用的图标。我们在编写用户界面文档时会引用 Octicons，并在表格中使用它们来指示二进制值。请在 Octicons 网站上查找特定 Octicons 的名称。

如果您引用的是界面中出现的 Octicon，请确定该 Octicon 是 UI 元素的完整标签（例如，仅用 “+” 标记的按钮），还是仅作为装饰且还有其他标签（例如，按钮标记为 “+ Add message”）。

  • 如果 Octicon 是完整标签，请使用浏览器的开发者工具检查该 Octicon 并确定屏幕阅读器用户将听到的内容。然后，将该文本用于 aria-label（例如，{% octicon "plus" aria-label="Add file" %}aria-label，而是其外层元素（如 <summary> 或 <div>）拥有。
    • 某些用作标签的 Octicon 具有动态的 aria-label，会根据 UI 元素的状态或用户输入而改变。例如，当有人有两个安全策略 Policy A 和 Policy B 时，界面会显示两个垃圾桶 Octicon，分别标记为 {% octicon "trash" aria-label="Delete Policy A" %} 和 {% octicon "trash" aria-label="Delete Policy B" %}。对于动态 aria-label，由于我们无法在文档中写出用户实际看到的确切标签，建议描述 Octicon 并给出占位符示例（例如，"{% octicon "trash" aria-label="The trash icon, labeled 'Delete YOUR-POLICY-NAME'." %}"）。这有助于他人识别 Octicon 以及其标签含义，并在进行视觉描述时提供上下文。
  • 如果 Octicon 仅作装饰用途，通常会使用 aria-hidden=true 属性对屏幕阅读器隐藏。若如此，为了与产品保持一致，请在文档的 Liquid 语法中也使用 aria-hidden="true"（例如，"{% octicon "plus" aria-hidden="true" %} Add message"）。

如果您以其他方式使用 Octicon，例如在表格中使用 “check” 与 “x” 图标来表示二进制值，请使用 aria-label 来描述 Octicon 的含义，而非其视觉外观。例如，在表格的 “Supported” 列使用 “x” 图标时，请将 aria-label 设置为 “Not supported”。更多信息请参阅 样式指南。

Octicons 使用示例

{% octicon "<name of Octicon>" %}
{% octicon "plus" %}
{% octicon "plus" aria-label="Add file" %}
"{% octicon "plus" aria-hidden="true" %} Add file"

操作系统标签

我们偶尔需要为不同的操作系统编写文档。每个操作系统可能需要一套不同的指令。我们使用操作系统标签来区分每个操作系统的信息。

操作系统标签使用示例

{% mac %}

These instructions are pertinent to Mac users.

{% endmac %}

{% linux %}

 These instructions are pertinent to Linux users.

{% endlinux %}

{% windows %}

These instructions are pertinent to Windows users.

{% endwindows %}

您可以在文章的 YAML frontmatter 中定义默认平台。更多信息请参阅 使用 YAML frontmatter。

工具标签

我们偶尔需要编写针对不同工具的文档。例如，GitHub UI、GitHub CLI、GitHub Desktop、GitHub Codespaces 和 Visual Studio Code 可能使用不同的步骤来完成相同的任务。我们使用工具标签来控制每个工具显示的信息。

GitHub Docs 为 GitHub 产品和选定的第三方扩展维护工具标签。请查看 all-tools.ts 对象以获取所有受支持工具的列表。

在极少数情况下，我们会添加新工具。添加新工具前，请阅读 在文章中创建工具切换器。要添加新工具，请在 lib/all-tools.ts 中的 allTools 对象里添加一个键值对。键是您在文章中引用该工具时使用的标签，值是工具在文章顶部工具选择器中显示的名称。

您可以在 YAML frontmatter 中为文章定义默认工具。更多信息请参阅 使用 YAML frontmatter。

工具标签使用示例

{% api %}

These instructions are pertinent to API users.

{% endapi %}

{% bash %}

These instructions are pertinent to Bash shell commands.

{% endbash %}

{% cli %}

These instructions are pertinent to GitHub CLI users.

{% endcli %}

{% codespaces %}

These instructions are pertinent to Codespaces users. They are mostly used outside the Codespaces docset, when we want to refer to how to do something inside Codespaces. Otherwise `webui` or `vscode` may be used.

{% endcodespaces %}

{% curl %}

These instructions are pertinent to curl commands.

{% endcurl %}

{% desktop %}

 These instructions are pertinent to GitHub Desktop.

{% enddesktop %}

{% importer_cli %}

These instructions are pertinent to GitHub Enterprise Importer CLI users.

{% endimporter_cli %}

{% javascript %}

These instructions are pertinent to javascript users.

{% endjavascript %}

{% jetbrains %}

These instructions are pertinent to users of JetBrains IDEs.

{% endjetbrains %}

{% powershell %}

These instructions are pertinent to `pwsh` and `powershell` commands.

{% endpowershell %}

{% vscode %}

These instructions are pertinent to VS Code users.

{% endvscode %}

{% webui %}

These instructions are pertinent to GitHub UI users.

{% endwebui %}

可重用和变量文本字符串

可重用字符串（通常称为内容引用或 conref）包含在文档中被多处使用的内容。创建这些引用可以让我们只在一个位置更新内容，而不是在每个出现该字符串的地方都修改。

对于较长的字符串，我们使用可重用项；对于较短的字符串，则使用变量。有关可重用项和变量的更多信息，请参阅 创建可重用内容。

表格管线符号

GitHub Docs 中的每一行表格都必须以管线符号 | 开始并结束，即使该行仅包含 Liquid 版本控制内容也不例外。

| Where is the table located? | Does every row end with a pipe? |
| --- | --- |
| {% ifversion some-cool-feature %} |
| GitHub Docs | Yes |
| {% endif %} |

表格行标题

如果您创建的表格第一列用于放置行标题，请在表格外包裹 Liquid 标记 {% rowheaders %} {% endrowheaders %}。有关在表格中使用正确标记的更多信息，请参阅 样式指南。

带行标题的示例表格

{% rowheaders %}

|             | Mona | Tom    | Hobbes |
|-------------|------|--------|--------|
|Type of cat  | Octo | Tuxedo | Tiger  |
|Likes to swim| Yes  | No     | No     |

{% endrowheaders %}

不带行标题的示例表格

| Name   | Vocation         |
| ------ | ---------------- |
| Mona   | GitHub mascot    |
| Tom    | Mouse antagonist |
| Hobbes | Best friend      |

带代码块的表格

虽然通常不建议在表格中包含代码块等块级项目，但在特定情况下可能是合适的。

由于 GitHub Flavored Markdown 中的表格 不能包含换行或块级结构，您必须使用 HTML 标记来编写表格结构。

当 HTML 表格中包含代码块时，表格宽度可能会超过页面内容的常规宽度，并且会溢出到通常显示小目录的区域。

如果发生这种情况，请在 <table> HTML 标记上添加以下 CSS 样式：

<table style="table-layout: fixed;">

有关此用法的当前示例，请参阅 使用 GitHub Actions 管理您的工作。

指向 docs 仓库中文档的链接必须以产品 ID（如 /actions 或 /admin）开头，并包含完整的文件路径，但不要包含文件扩展名。例如，/actions/creating-actions/about-custom-actions。

图片路径必须以 /assets 开头，并包含完整的文件路径和文件扩展名。例如，/assets/images/help/settings/settings-account-delete.png。

指向 Markdown 页面 的链接在服务器端会进行一些转换，以匹配当前页面的语言和版本。这些转换的处理位于 lib/render-content/plugins/rewrite-local-links 中。

例如，如果您在内容文件中包含以下链接：

/github/writing-on-github/creating-a-saved-reply

在 GitHub Docs 上查看时，链接会带上语言代码进行渲染。

/en/github/writing-on-github/creating-a-saved-reply

在 GitHub Enterprise Server 文档上查看时，还会同时包含版本信息。

/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply

有关链接的更多信息，请参阅 样式指南。

由于站点是动态的，它不会为每个不同版本的文章构建 HTML 文件。相反，它会为每个版本的文章生成一个“永久链接”。此链接基于文章的 versions frontmatter 生成。

注意

自 2021 年初起，free-pro-team@latest 版本不会包含在 URL 中。一个名为 lib/remove-fpt-from-path.ts 的辅助函数会从 URL 中移除该版本。

例如，可在当前受支持版本中使用的文章的永久链接 URL 如下：

  • /en/get-started/git-basics/set-up-git
  • /en/enterprise-cloud@latest/get-started/git-basics/set-up-git
  • /en/enterprise-server@3.10/get-started/git-basics/set-up-git
  • /en/enterprise-server@3.9/get-started/git-basics/set-up-git
  • /en/enterprise-server@3.8/get-started/git-basics/set-up-git
  • /en/enterprise-server@3.7/get-started/git-basics/set-up-git
  • /en/enterprise-server@3.6/get-started/git-basics/set-up-git

不在 GitHub Enterprise Server 中提供的文章只会有一个永久链接。

  • /en/get-started/git-basics/set-up-git

注意

如果您是内容贡献者，在向文档添加链接时无需考虑受支持的版本。遵循上述示例，如果您想引用一篇文章，只需使用其相对位置即可：/github/getting-started-with-github/set-up-git。

在链接到另一篇 GitHub Docs 页面时，请使用标准的 Markdown 语法如 []()，但将页面标题替换为 AUTOTITLE。GitHub Docs 应用在渲染期间会用链接页面的标题替换 AUTOTITLE。此关键字区分大小写，请务必正确输入，否则替换将失效。

  • 有关更多信息，请参阅 [AUTOTITLE](/path/to/page)。
  • 有关更多信息，请参阅 [AUTOTITLE](/path/to/page#section-link)。
  • 有关更多信息，请参阅 [AUTOTITLE](/path/to/page?tool=TOOLNAME) 中的 TOOLNAME 文档。

注意

同页章节链接不支持此关键字，请直接输入完整的标题文本。

在文档的其他版本中链接到当前文章

有时您可能希望从一篇文章链接到同一文章的不同产品版本。例如，

  • 您提到了某些功能在免费、专业或团队计划中不可用，并希望链接到 GitHub Enterprise Cloud 版本的同一页面。
  • GitHub Enterprise Server 版本的文章描述了该版本随附的功能，但站点管理员可以将其升级到在 GitHub Enterprise Cloud 上使用的最新功能版本。

您可以使用 currentArticle 属性直接链接到页面的其他版本。这意味着即使文章 URL 发生变化，链接仍能直接工作。

{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest{{ currentArticle }}).{% endif %}

防止转换

有时您想在 Enterprise 内容中链接到仅适用于 Dotcom 的文章，并且不希望链接被 Enterprise 化。为防止转换，应在路径中包含首选版本。

[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service)

有时内容的规范主页会移出 docs 站点。src/redirects/lib/external-sites.json 中包含的链接均不会被重写。请参阅 contributing/redirects.md 了解此类重定向的更多信息。

我们的文档中包含使用旧文件路径（如 /article/article-name 或 /github/article-name）的链接，也包含使用过去名称引用文章的链接。两种链接类型均因重定向而正常工作，但它们属于错误。

在为文章添加链接时，请使用当前的文件路径和文章名称。

© . This site is unofficial and not affiliated with GitHub, Inc.