文档 Writers' Toolkit 写作 Markdown 指南

Markdown 指南

Grafana 网站使用静态网站生成器 Hugo 来生成文档页面。

Hugo 使用名为 Goldmark 的 Markdown 解析器，它支持 CommonMark 风格的 Markdown，包括一些扩展功能。欲了解更多信息，请参阅 CommonMark 规范，以及 CommonMark 快速参考指南。

所有技术文档（无论是长篇文本还是 UI 中的微文案）均使用句子大小写。

• 这是句子大小写
• 这是标题大小写

标题

与 HTML 标题（<h1>、<h2> 和 <h3>）类似，在 Markdown 中，# 符号（或称 hash 标签）用于创建不同级别的标题

示例

• # 是一级标题。
• ## 是二级标题。
• ### 是三级标题。

对于页面标题，请使用一个 #。对于每个子标题，请使用两个 ## 符号。

标识符

每个标题都有一个自动生成的标识符，您可以使用它来链接到页面内的该标题。要从标题派生生成的标识符，请参阅链接到页面标题。

您也可以显式设置标题标识符。以下 Markdown 示例将标题标识符设置为 alternative-heading-id

markdown 复制

# Heading {#alternative-heading-id}

标题禁忌

• 避免堆叠标题。不要在一个标题后面紧跟另一个标题，中间没有任何内容。
• 避免跳过标题级别。例如，在一个 # 之后，使用 ##，而不是 ###。
• 避免在标题中使用连字符。
• 除了 (Optional) 外，不要包含带括号的词，如 (Important)。
• 避免重复标题。如果需要重用同一标题，尽量保持含义一致。尽最大努力避免让用户困惑。

粗体和强调

• 要使文本显示为**粗体**，请使用 **两个星号** 将文本括起来。
• 要*强调*文本，请使用 _单下划线_ 将文本括起来。

不要使用单星号（*），因为它们容易与用于粗体的两个星号混淆。

要了解如何在文档中使用粗体和强调，请参阅文本格式。

链接

有关在 Grafana Labs 仓库内部和外部创建链接的信息，请参阅链接。

Markdown 中有两种链接形式：内联式和参考式。

创建内联式链接时，您在文档中同一位置定义链接文本和目标地址。以下代码片段演示了内联式链接，链接文本为“要显示的链接文本”，目标地址为 https://example.com。

markdown 复制

[Link text to display](https://example.com)

创建参考式链接时，您定义链接文本，然后使用标签引用文档中其他位置（通常在文件末尾）定义的链接目标地址。参考式链接允许您只定义一次链接目标地址，然后在文档中多次重用该标签。

以下代码片段演示了参考式链接，链接文本为“要显示的链接文本”，目标地址为 https://example.com，并使用标签“label”。

markdown 复制

[Link text to display][label]

[label]: https://example.com

您也可以定义没有显式标签的参考式链接。在这种情况下，标签就是链接文本本身。

以下代码片段使用无序列表演示了两种使用隐式标签编写参考式链接的不同方式。

markdown 复制

- [Link text to display]
- [Link text to display][]

[Link text to display]: https://example.com

块引用

通过使用右尖括号（>）在文本中包含块引用。对于注释、提示、警告和注意告诫，请优先使用 admonition shortcode。

示例

markdown 复制

> This text is in block quotes.

效果如下

这段文本在块引用中。

代码块

使用三个反引号创建围栏式代码块。

第一个三个反引号后面的信息字符串描述了代码块中包含的语言。网站使用此信息为代码示例应用语法高亮。欲了解更多信息，请参阅语法高亮。

表格

通过使用竖线（|）字符分隔表格标题来构建表格。使用一系列由竖线字符分隔的破折号（-）组成的列线，将表格标题行与数据分隔开。最后，通过使用竖线字符分隔单元格数据来构建一系列表格数据行。

不要使用 <br> 元素创建段落或列表。相反，请使用 <p> 元素创建段落，或使用 <ol> 或 <ul> 元素创建列表。

有关表格的风格指南，请参阅Google 开发者文档风格指南。

示例

markdown 复制

| Heading one   | Heading two   |
| ------------- | ------------- |
| Cell one data | Cell two data |

效果如下

有序列表

使用重复的列表编号，即在每个列表项前都使用 1. 而不是实际数字，以避免列表编号不一致。Markdown 渲染器会自动递增列表编号。

对于子步骤，也使用重复编号。

将段落作为列表项书写时，必须使用正确的缩进

• 列表项中的每一行都必须与前一个列表项的缩进一致。
• 每个段落前面必须有一个空行。

对于独立的有序列表，列表项第二句的缩进是三个空格。

示例

markdown 复制

1. First
1. Second
1. Third

效果如下

1. 第一项
2. 第二项
3. 第三项

markdown 复制

1. First
   1. Write a sub-step.
   1. Write another sub-step.
   1. Write yet another sub-step.
1. Second
1. Third

效果如下

1. 第一项
   1. 写一个子步骤。
   2. 写另一个子步骤。
   3. 再写一个子步骤。
2. 第二项
3. 第三项

markdown 复制

1. First paragraph in first entry.
   Second sentence in first paragraph.

   Second paragraph in first entry.

1. First paragraph in second entry.

效果如下

1. 第一项中的第一个段落。第一个段落中的第二句话。

   第一项中的第二个段落。

2. 第二项中的第一个段落。

无序列表

通过使用连字符（-）构建无序列表。当列表项没有特定顺序时，使用无序列表。

将段落作为列表项书写时，必须使用正确的缩进

• 列表项中的每一行都必须与前一个列表项的缩进一致。
• 每个段落前面必须有一个空行。

对于独立的无序列表，列表项第二句的缩进是两个空格。

示例

markdown 复制

- One item
- Another item
- And another list item

效果如下

• 一项
• 另一项
• 还有一项列表项

图片

使用以下语法在文档中包含图片 ![<替代文本>](<URL> "<标题>")。

示例

• ![Grafana 徽标](/link/to/grafanalogo/logo.png "Grafana 徽标")
• ![警报测试规则](/static/img/docs/folder_name/alert_test_rule.png "示例标题")

如果需要更多图片选项，例如添加标题或控制图片大小，可以使用 figure shortcode。在 Markdown 中，HTML 是有效的，但应避免使用。

如果无法使用 figure shortcode 实现所需样式，请提交 issue。

描述列表

Hugo 使用的 Markdown 解析器 Goldmark 内置支持描述列表。您可以使用描述列表来列出术语及其定义，或核心概念。语法如下

markdown 复制

term
: description_text

您可以在描述列表中添加更多标记。例如，可以将定义术语格式化为粗体文本。

markdown 复制

**Fast compile times**
: The Go compiler is fast!

**Ecosystem**
: Go tooling is excellent.

前面的描述列表显示如下

快速编译时间

Go 编译器速度很快。

生态系统

Go 工具非常出色。

注释

您可以包含不会在发布输出中显示的注释

[comment]: <> (要显示的注释文本)

Shortcodes

Shortcodes 是您在源文件中使用的代码片段，用于调用内置或自定义模板。Shortcode 模板避免了在 Markdown 中使用 HTML 的需要，并确保了整个文档集的一致性。要了解如何使用 shortcodes，请参阅Shortcodes。