在 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. 在您的仓库名称下，单击 **操作**。

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

    这是列表中的另一个段落。

  2. 这是下一项。

提示标签

提示突出显示用户需要了解的重要信息。我们使用标准格式和颜色来表示四种不同的提示类型：注释、提示、警告和危险通知。

有关何时使用提示以及如何在 Markdown 中格式化提示的信息，请参阅 "样式指南。"。

提示示例

> [!NOTE] Keep this in mind.

> [!NOTE]
> Generally callouts 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 前置 matter 属性的文章。有关如何编写和设置代码注释的更多信息，请参见 "注释代码示例."

带注释的代码示例

```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 上使用代码注释的文章，请参阅“使用脚本在运行器上测试代码”。

Octicons

Octicons 是 GitHub 界面中使用的图标。我们在记录用户界面时引用 Octicons，并在表格中指示二进制值。在 Octicons 网站 上查找特定 Octicons 的名称。

如果您引用的是 UI 中出现的 Octicon，请确定 Octicon 是 UI 元素的整个标签（例如，仅用“+”标记的按钮），还是除了另一个标签之外，它只是装饰性的（例如，一个按钮标记为“+ 添加消息”）。

  • 如果 Octicon 是整个标签，请使用浏览器的开发者工具检查 Octicon 并确定屏幕阅读器用户将听到什么。然后，将该文本用于 aria-label（例如，{% octicon "plus" aria-label="添加文件" %}）。有时，在 UI 中，Octicon 本身将没有 aria-label，但周围的元素（如 <summary> 或 <div> 标签）将有。
    • 一些用作标签的 Octicons 具有动态的 aria-label 元素，这些元素会根据 UI 元素的状态或用户输入而改变。例如，当某人拥有两个安全策略 - 策略 A 和 策略 B - 他们的 UI 将显示两个垃圾桶 Octicons，分别标记为 {% octicon "trash" aria-label="删除策略 A" %} 和 {% octicon "trash" aria-label="删除策略 B" %}。对于动态的 aria-label 元素，由于我们无法记录人们会遇到的确切 aria-label，因此请描述 Octicon 和标签的占位符示例（例如，"{% octicon "trash" aria-label="垃圾桶图标，标记为 '删除 YOUR-POLICY-NAME'。" %}"）。这将帮助人们识别 Octicon 及其标签，并为与视觉描述 Octicon 的人协作提供上下文。
  • 如果 Octicon 是装饰性的，它很可能被 aria-hidden=true 属性隐藏在屏幕阅读器中。如果是这样，为了与产品保持一致，在文档中 Octicon 的 Liquid 语法中也使用 aria-hidden="true"（例如，"{% octicon "plus" aria-hidden="true" %} 添加消息"）。

如果您以其他方式使用 Octicon，例如使用“勾号”和“叉号”图标在表格中反映二进制值，请使用 aria-label 描述 Octicon 的含义，而不是其视觉特征。例如，如果您在表格的“支持”列中使用“叉号”图标，请使用“不支持”作为 aria-label。有关更多信息，请参阅“样式指南”。

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 前文中定义默认平台。有关更多信息，请参阅“使用 YAML 前文”。

工具标签

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

GitHub Docs 为 GitHub 产品和选定的第三方扩展维护工具标签。请参阅 all-tools.js 对象（位于 github/docs 存储库中），了解所有支持的工具列表。

在极少数情况下，我们会添加新工具。在添加新工具之前，请阅读“在文章中创建工具切换器”。要添加新工具，请在 lib/all-tools.js 中的 allTools 对象中添加一个键值对作为条目。键是您将在文章中用来引用该工具的标签，而值是该工具在文章顶部的工具选择器中将如何标识。

您可以在 YAML 前文中为文章定义默认工具。有关更多信息，请参阅“使用 YAML 前文”。

工具标签的使用示例

{% 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 表格包含代码块时，表格的宽度可能会超过页面内容的常规宽度，然后溢出到通常包含目录的小表格的区域。

如果发生这种情况，请将以下 CSS 样式添加到 <table> HTML 标签中

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

有关此用法的当前示例，请参阅 "示例。"。

指向 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.com 文档中查看时，链接将使用语言代码进行渲染

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

在 GitHub Enterprise Server 文档中查看时，版本也会包含在内

/en/[email protected]/github/writing-on-github/creating-a-saved-reply

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

由于网站是动态的，因此它不会为每篇文章的不同版本构建 HTML 文件。相反，它会为每篇文章的每个版本生成一个“永久链接”。它是根据文章的 versions 前端内容 来实现的。

注意：截至 2021 年初，free-pro-team@latest 版本未包含在 URL 中。一个名为 lib/remove-fpt-from-path.js 的辅助函数会从 URL 中删除该版本。

例如，一篇在当前支持的版本中可用的文章将具有以下永久链接 URL

  • /en/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-cloud@latest/get-started/getting-started-with-git/set-up-git
  • /en/[email protected]/get-started/getting-started-with-git/set-up-git
  • /en/[email protected]/get-started/getting-started-with-git/set-up-git
  • /en/[email protected]/get-started/getting-started-with-git/set-up-git
  • /en/[email protected]/get-started/getting-started-with-git/set-up-git
  • /en/[email protected]/get-started/getting-started-with-git/set-up-git

一篇在 GitHub Enterprise Server 中不可用的文章将只有一个永久链接

  • /en/get-started/getting-started-with-git/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 %}

防止转换

有时您想在企业内容中链接到 Dotcom 独占文章，并且不希望链接被企业化。为了防止转换，您应该在路径中包含首选版本。

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

有时内容的规范主页会移到文档网站之外。src/redirects/lib/external-sites.json 中包含的所有链接都不会被重写。有关此类重定向的更多信息，请参阅 contributing/redirects.md。

我们的文档包含使用旧版文件路径的链接，例如/article/article-name或/github/article-name。我们的文档还包含指向过去名称文章的链接。这两种类型的链接都通过重定向正常工作，但它们是错误。

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