文档速查表

文档文件混合使用了Markdown和MyST语法。

有关语法帮助和约定，请参阅以下部分。

标题

输入	描述
# Title	页面标题和 H1 标题
## Heading	H2 标题
### Heading	H3 标题
#### Heading	H4 标题
…	更多标题

遵守以下约定

• 不要在没有中间文本的情况下使用连续的标题。

• 标题使用句子样式（仅首字母大写）。

• 不要跳过级别（例如，始终在 H2 后使用 H3，而不是 H4）。

内联格式

输入	输出
{guilabel}`UI element`	UI 元素
`code`	代码
{command}`command`	命令
*斜体*	斜体
**粗体**	粗体

遵守以下约定

• 谨慎使用斜体。斜体的常见用法是标题和名称（例如，在引用无法链接到的章节标题时，或在引入概念名称时）。

• 谨慎使用粗体。粗体的常见用法是 UI 元素（“单击确定”）。避免使用粗体进行强调，而是重写句子以表达您的观点。

代码块

使用三个反引号开始和结束代码块

```

您可以在反引号后指定代码语言以强制使用特定的词法分析器，但在许多情况下，默认词法分析器也能很好地工作。

输入	输出
``` # Demonstrate a code block code: - example: true ```	# Demonstrate a code block code: - example: true
```yaml # Demonstrate a code block code: - example: true ```	# Demonstrate a code block code: - example: true

要在代码块中包含反引号，请增加周围反引号的数量

输入	输出
```` ``` ````	```

链接

如何链接取决于您是链接到外部 URL 还是链接到文档中的其他页面。

外部链接

对于外部链接，仅使用 URL，或者如果您想覆盖链接文本，则使用 Markdown 语法。

输入	输出
https://linuxcontainers.cn/incus	https://linuxcontainers.cn/incus
[Incus](https://linuxcontainers.cn/incus)	Incus

要将 URL 显示为文本并阻止其成为链接，请添加<span></span>

输入	输出
https:/<span></span>/linuxcontainers.org/incus	https://linuxcontainers.org/incus

内部引用

对于内部引用，支持 Markdown 和 MyST 语法。不过，在大多数情况下，您应该使用 MyST 语法，因为它会自动解析链接文本并在 GitHub 渲染中给出链接指示。

引用页面

要引用文档页面，请使用 MyST 语法自动提取链接文本。覆盖链接文本时，请使用 Markdown 语法。

输入	输出	GitHub 上的输出	状态
{doc}`index`	Incus	{doc}index	首选。
[](index)	Incus		不要使用。
[Incus documentation](index)	Incus 文档	Incus 文档	覆盖链接文本时首选。
{doc}`Incus documentation <index>`	Incus 文档	{doc}Incus documentation <index>	覆盖链接文本时的替代方法。

遵守以下约定

• 仅在必要时覆盖链接文本。如果您可以使用文档标题作为链接文本，请这样做，因为如果标题更改，文本将自动更新。

• 切勿使用与自动生成的文本相同的文本“覆盖”链接文本。

引用部分

要引用文档中的某个部分（在同一页面或其他页面上），您可以向其添加目标并引用该目标，或者您可以结合使用自动生成的锚点和文件名。

遵守以下约定

• 为核心部分和“典型”链接位置添加目标，因此您预计它们将被频繁链接。对于“一次性”链接，您可以使用自动生成的锚点。

• 仅在必要时覆盖链接文本。如果您可以使用章节标题作为链接文本，请这样做，因为如果标题更改，文本将自动更新。

• 切勿使用与自动生成的文本相同的文本“覆盖”链接文本。

使用目标

您可以在文档中的任何位置添加目标。但是，如果目标元素没有标题，则必须指定链接文本。

输入	输出	GitHub 上的输出	描述
(target_ID)=		(target_ID)=	添加目标target_ID。
{ref}`a_section_target`	引用部分	{ref}a_section_target	引用具有标题的目标。
{ref}`link text <a_random_target>`	链接文本	{ref}link text <a_random_target>	引用目标并指定标题。
[`option name\](a_random_target)	option name	option name（链接已断开）	如果需要在链接文本上使用标记，请使用 Markdown 语法。

使用自动生成的锚点

必须使用 Markdown 语法才能使用自动生成的锚点。在同一文件中链接时，可以省略文件名。

输入	输出	GitHub 上的输出	描述
[](#referencing-a-section)	引用部分		不要使用。
[link text](#referencing-a-section)	链接文本	链接文本	覆盖链接文本时首选。

导航

每个文档页面都必须作为导航中另一个页面的子页面包含。

这是通过父页面中的toctree指令实现的

```{toctree}
:hidden:

subpage1
subpage2
```

如果某个页面不应包含在导航中，可以通过在文件顶部放置以下指令来抑制生成的构建警告

---
orphan: true
---

谨慎使用孤立页面，并且仅在有明确理由时才使用。

列表

输入	输出
- Item 1 - Item 2 - Item 3	项目 1 项目 2 项目 3
1. Step 1 1. Step 2 1. Step 3	步骤 1 步骤 2 步骤 3
1. Step 1 - Item 1 * Subitem - Item 2 1. Step 2 1. Substep 1 1. Substep 2	步骤 1 项目 1 子项目 项目 2 步骤 2 子步骤 1 子步骤 2

遵守以下约定

• 在编号列表中，对所有项目使用1.来自动生成步骤编号。

• 对无序列表使用-。使用嵌套列表时，可以使用*作为嵌套级别。

定义列表

输入	输出
Term 1 : Definition Term 2 : Definition	术语 1 定义 术语 2 定义

表格

可以使用标准的 Markdown 表格。但是，使用 rST 列表表格语法通常更容易。

两种标记都生成以下输出

标题 1	标题 2
单元格 1 单元格 1 的第二段	单元格 2
单元格 3	单元格 4

Markdown 表格

| Header 1                           | Header 2 |
|------------------------------------|----------|
| Cell 1<br><br>2nd paragraph cell 1 | Cell 2   |
| Cell 3                             | Cell 4   |

列表表格

```{list-table}
   :header-rows: 1

* - Header 1
  - Header 2
* - Cell 1

    2nd paragraph cell 1
  - Cell 2
* - Cell 3
  - Cell 4
```

注释

输入	输出
```{note} A note. ```	注意 一条注释。
```{tip} A tip. ```	提示 一条提示。
```{important} Important information ```	重要 重要信息。
```{caution} This might damage your hardware! ```	警告 这可能会损坏您的硬件！

遵守以下约定

• 谨慎使用注释。

• 仅使用以下注释类型：note、tip、important、caution

• 仅在存在硬件损坏或数据丢失的明确风险时才使用警告。

图像

输入	输出
```{figure} https://linuxcontainers.cn/incus/docs/main/_static/tag.png :width: 100px :alt: Alt text Figure caption ```	图注

遵守以下约定

• 对于doc目录中的图片，请以/开头路径（例如，/images/image.png）。

• 对屏幕截图使用 PNG 格式，对图形使用 SVG 格式。

重用

与普通 Markdown 相比，MyST 的一大优势在于它允许重用内容。

替换

要重用句子或段落而无需过多标记和特殊格式，请使用替换。

可以在以下位置定义替换

• 在substitutions.yaml文件中。在此文件中定义的替换在所有文档页面中都可用。

• 在单个文件的顶部，采用以下格式

  ---
  myst:
    substitutions:
      reuse_key: "This is **included** text."
      advanced_reuse_key: "This is a substitution that includes a code block:
                         ```
                         code block
                         ```"
  
  ---
  

可以通过在reuse/substitutions.py中定义默认替换并在文件顶部覆盖它来组合这两种选项。

输入	输出
{{reuse_key}}	这是**包含的**文本。
{{advanced_reuse_key}}	这是一个包含代码块的替换：code block

遵守以下约定

• 替换在 GitHub 上不起作用。因此，请使用指示包含文本的键名（例如，note_not_supported而不是reuse_note）。

文件包含

要重用更长的部分或具有更高级标记的文本，可以将内容放在单独的文件中，并在多个位置包含该文件或文件的部分内容。

不能在被重用的内容中放置任何目标（因为对该目标的引用将变得模棱两可）。但是，可以在包含文件之前放置一个目标。

通过结合文件包含和替换，甚至可以替换包含文本的部分内容。

输入	输出
% Include parts of the content from file [../README.md](../README.md) ```{include} ../README.md :start-after: <!-- Include start Incus intro --> :end-before: <!-- Include end Incus intro --> ```	它为在容器或虚拟机中运行和管理完整的 Linux 系统提供了统一的体验。Incus 支持大量 Linux 发行版的镜像（官方 Ubuntu 镜像和社区提供的镜像），并且构建在一个非常强大但非常简单的 REST API 之上。Incus 的规模从单台机器上的一个实例扩展到完整数据中心机架中的集群，使其适合运行开发和生产中的工作负载。 Incus 允许您轻松设置一个感觉像小型私有云的系统。您可以在保持资源优化的同时，以有效的方式运行任何类型的工作负载。 如果您想容器化不同的环境或运行虚拟机，或者通常以经济高效的方式运行和管理您的基础设施，则应考虑使用 Incus。 您可以在以下网址在线试用 Incus：https://linuxcontainers.cn/incus/try-it/

遵守以下约定

• 文件包含在 GitHub 上不起作用。因此，始终添加一条指向包含文件的注释。

• 要选择文本的部分内容，请为起始点和结束点添加 HTML 注释，并使用:start-after:和:end-before:，如果可能。可以将:start-after:和:end-before:与:start-line:和:end-line:结合使用，如果需要。但是，仅使用:start-line:和:end-line:容易出错。

选项卡

输入	输出
````{tabs} ```{group-tab} Tab 1 Content Tab 1 ``` ```{group-tab} Tab 2 Content Tab 2 ``` ````	选项卡 1选项卡 2 选项卡 1 内容

可折叠部分

rST 不支持详细信息部分，但可以插入 HTML 来创建它们。

输入	输出
<details> <summary>Details</summary> Content </details>	详细信息 内容

词汇表

可以在任何文件中定义词汇表术语。理想情况下，所有术语都应该在一个词汇表文件中收集，然后可以从任何文件中引用它们。

输入	输出
```{glossary} example term Definition of the example term. ```	示例术语 示例术语的定义。
{term}`example term`	示例术语

更多有用的标记

输入	输出
```{versionadded} X.Y ```	在版本 X.Y 中添加。
{abbr}`API (Application Programming Interface)`	API

自定义扩展

文档使用了一些自定义扩展。

相关链接

可以通过在页面顶部添加以下字段，将相关网站的链接添加到侧边栏

relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)

要覆盖标题，请使用 Markdown 语法。请注意，空格会被忽略；如果标题中需要空格，请将其替换为 ，如果 Sphinx 因元数据值以[开头而抱怨，请将该值包含在引号中。

要添加指向 Discourse 主题的链接，请在页面顶部添加以下字段（其中12345是 Discourse 主题的 ID）

discourse: 12345

YouTube 链接

要添加指向 YouTube 视频的链接，请使用以下指令

输入	输出
```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 :title: Demo ```	▶ 在 YouTube 上观看

视频标题会自动提取并在悬停在链接上时显示。要覆盖标题，请添加:title:选项。

拼写例外

如果需要使用不符合拼写约定的单词，但在特定上下文中是正确的，可以通过将其用{spellexception}包围来将其从拼写检查器中豁免。

输入	输出
{spellexception}`PurposelyWrong`	PurposelyWrong

终端输出

要显示带有命令和输出的终端视图，请使用以下指令

输入	输出
```{terminal} :input: command number one :user: root :host: vm output line one output line two :input: another command more output ```	root@vm:~# command number one output line oneoutput line two root@vm:~# another command more output

输入指定为:input:选项（或作为指令的主要内容的一部分，以:input:为前缀）。输出是指令的主要内容。

要覆盖默认的提示符（user@host:~$），请指定:user:和/或:host:选项。要使终端水平滚动而不是换行显示长行，请添加:scroll:。