文档风格指南¶

本指南包括有关编写新内容和翻译现有内容的预期风格、MkDocs 特定语法、各种所需工具和文档翻译的信息。

一般风格¶

页眉和标题的第一个单词应大写。
我们倾向于使用美式拼写法，但对程序特定的口语（如 "apps"）和名词的动词化（如 "scrollable"）有一定的自由度。
artefact "和 "artefacts "的拼写如图所示。
我们在句号后使用单个空格。
我们使用单个连字符，两侧加空格作为长破折号（或HTML中的—字面量）。
任何对产品名称的引用都应使用该产品的首选大写字母。(例如："macOS"、"GTK"、"pytest"、"Pygame"、"PyScript"）。
如果一个术语是 "作为代码 "使用的，那么它就应该作为内联代码引用，用单个回车键将其包裹起来，而不是添加到字典中。
在描述用户应采取的操作时，我们避免使用"简单地"、"仅仅"或"轻松地"等措辞。这些词汇可能被解读为贬义，尤其当用户遇到困难时。

交叉引用信息¶

应尽可能交叉引用文档中的内容。本节将介绍各种交叉引用的方法，每种方法都基于被引用信息的类型。

MkDocs 可渲染标准 Markdown 格式的链接。标准 Markdown 格式的网络超链接如下：

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

您也可以使用这种格式链接到本地文件：

[Link text](path/to/file.md)

引用文件的特定部分或 API 文档需要使用 MkDocs 引用链接格式。

自定义 Markdown 锚点和内容交叉引用¶

Markdown 会根据标题的内容为所有标题（单行中以 1 到 6 个 # 符号开头的任何内容）生成锚点。例如，本节生成的锚点是："custom-markdown-anchors-and-content-cross–referencing"。不过，由于我们的翻译工作方式，无论何时引用章节标题，都必须使用自定义锚点。

MkDocs 支持呈现引用链接语法，允许您使用修改后的 Markdown 链接来链接文档中的各种其他元素。这包括链接到自定义 Markdown 标题和文本锚点等。

MkDocs 引用链接是格式如下的任何链接：

[Link text][link-target]

需要自定义标题和内容锚点

任何通过 BeeWare 文档中的 MkDocs 引用链接在文本内容中引用的页眉或内容部分都必须附加自定义锚点。否则，在翻译页眉内容时可能会破坏链接。

如果需要链接到标题锚点，则需要为目标内容生成自定义锚点。设置自定义锚点的一般语法如下：

# Header text { #anchor-name }

例如，将本节的锚点自定义为 "自定义锚点"，格式如下：

## Custom Markdown anchors { #custom-anchors }

您也可以在一般内容（包括文本和代码块）上创建锚点。在您希望链接的内容上方，应包含以下格式，上下换行：

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

创建自定义锚点后，您可以在同一文档中或文档的其他部分链接到这些锚点。

标准 Markdown 用于链接到同一文件中的锚点，其格式如下：

[Link text](#anchor-name)

使用 MkDocs 引用链接样式链接到单独文档中的锚点，其格式如下：

[Link text][anchor-name]

应用程序接口参考链接¶

MkDocs 引用链接还支持交叉引用 API 文档，包括文档中的类、类方法或属性，以及特定的外部文档引用。

无论您是从同一个文件还是从一个单独的文件链接，都有多个选项可用于链接到已记录的类或类方法或属性。链接到类等时，必须在第一组方括号中加上反斜线，以便将名称显示为内联代码。只有在使用不应显示为内联代码的自定义文本时，才不需要使用回车键。绝不能在第二组方括号中加入反斜线。

在显示命名空间的同时链接到类的格式如下：

[`module.ClassName`][]

在只显示类名的情况下链接到类的格式如下：

[`ClassName`][module.ClassName]

属性与上述相同，并包含属性名称。下面显示的是命名空间：

[`module.ClassName.attributename`][]

与类一样，只显示属性名称的格式如下：

[`attributename`][module.ClassName.attributename]

方法应在命名空间后显示"()"，因此其处理方式必须与属性不同。下面是链接方法的适当方式：

[`module.ClassName.methodname()`][module.ClassName.methodname]

下文仅显示类和方法名称。这也需要在名称后加上括号：

[`Classname.methodname()`][module.Classname.methodname]

您可以在显示任意文本的同时，使用与适用命名空间相同的方法链接到类、方法或属性。类的链接格式如下：

[link text][module.ClassName]

也可以直接链接到 Python 核心文档和 Pillow 文档。例如，链接到 int 的文档：

[`int`][]

链接到 Pillow Image 文档：

[`PIL.Image.Image`][]

代码块提示¶

语言和代码高亮¶

您可以指定代码块中包含的代码的语言，方法是在前三个回车键后加上语言名称，中间不留空格。这样在渲染代码时就会突出显示相应的代码。例如，要指定 Python 语言，您可以在代码块的开头使用 ``python.

控制台命令和复制按钮¶

如果您要包含控制台命令或带输出的命令，请根据您描述的是类 Unix（包括 macOS）操作系统还是 Windows，将其标注为 "console "或 "doscon"。您可以包含操作系统提供的提示；点击复制按钮时，只有命令会被复制。例如，如果您以 ``console 开始代码块，并包含以下内容：

$ mkdir test
$ ls
test

然后，点击代码块上的复制按钮将只复制命令，而忽略提示和输出。这样既能表明它们是控制台命令，又能让用户有效使用复制按钮。

突出显示特定代码行¶

您可以高亮特定的代码行。例如，要高亮第 2 行，您可以在语言后添加一个空格，然后跟上 {hl_lines="2"}。因此，您的代码块将以 ``python {hl_lines="2"} 开头。`.结果是

import toga
from toga.style.pack import COLUMN, ROW

您可以高亮多个不同的行。例如，python {hl_lines="3 5 9"}将高亮第 3、5 和 9 行。您还可以高亮一系列行。例如，python {hl_lines="3-8"} 将高亮第 3 行至第 8 行。例如，python {hl_lines="9-18 23-44"}可以高亮多个范围。

需要特定格式的 Markdown 元素¶

由于翻译文件的生成方式，必须在 Markdown 语法中为训诫、注释、制表符、Jinja 指令、图像标题和对齐方式等加入所需的换行符。

训诫和说明¶

训诫语的格式必须如下，包括确保在训诫语开始和结束前后加一个换行符：

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

任何受支持的警告类型都采用相同的方式处理。例如，注释警告需要相同的格式和换行符：

Content above.

/// note | Note title

Note text here.

///

Content below.

所有支持的告诫类型均可作为告诫使用。

标签式内容¶

标签内容的格式如下，包括在内容块的开始和结束前加入换行符：

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

带有嵌套告诫的制表符格式如下，包括内容块前后的换行符：

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

折叠内容¶

折叠内容的格式如下，包括换行符：

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

所有支持的警告类型均可用于折叠内容，但必须声明为details-admonitiontype。因此，"注释"类型的折叠块应为details-note（如上所示），"警告"类型的折叠块应为details-warning，依此类推。

金贾指令¶

文档中有一些功能在文本中使用了 Jinja 指令。任何使用 Jinja 指令功能的内容都需要用换行符包起来。例如，BeeWare 教程包含基于变量的 Jinja 条件句，用于决定在主页上显示什么告诫。其格式如下

Content above.



Content below.

还有一种语法用于替换符号或文本。这种语法是用一对匹配的双大括号将一个变量包起来，如果是在一行中，前后必须包括一个换行符。

Content above.

{{ variable }}

Content below.

图像格式¶

图片可以设置宽度，可以向左、向右或居中对齐（"居中 "需要注意）。图片应始终包含有意义的alt文本，以便于访问。

在图像上设置 300px 宽度的格式如下：

![Image alt text](../path/to/image.png){ width="300px" }

向左（或向右）对齐图像的格式如下：

![Image alt text](../path/to/image.png){ align=left }

为图像添加标题需要在前后加换行符，格式如下：

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

使用 align 属性无法将图像居中对齐。解决方法是在图片后面加上一个空标题，这样图片就会居中对齐。您必须在每个部分之间以及前后加上换行符。格式如下

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

具有特定 Markdown 格式的插件¶

下文将介绍如何使用需要特定 Markdown 格式的插件。

使用片段包含外部内容¶

有关如何从本地文件或 URL 中包含外部内容的详情，请参阅Snippets 扩展文档。只要文档不包含需要执行的金沙指令，就应使用 Snippets（金沙指令的执行与 Snippets 处理同时进行，因此文件中的任何金沙指令都不会被处理）。如果您希望使用分隔符来单独包含文件的特定部分，例如将源文件划分为多个部分并分别注入，那么 Snippets 就是必要的。

重要说明

我们使用 -8<- 作为 Snippets 标识符。文档中显示了多种选项，请遵循我们的风格。
在 BeeWare 文档工具共享内容中找到的文件被视为 "本地 "内容。因此，要么只使用文件名，如 -8<- "docs-style-guide.md"，要么如果内容在子目录中，只使用目录和文件名，如 -8<- "style/docs-style-guide.md"。
如果您通过 URL 从 GitHub 上的文件包含外部内容，您_must_必须使用原始内容 URL，否则无论您在哪里包含，都会呈现嵌入的完整网页。

使用宏将 BeeWare 文档工具共享内容包含在内¶

您还可以使用 Macros MkDocs 插件，从 BeeWare Docs 工具共享内容目录中添加内容。如果文档中包含需要执行的 Jinja 指令，则必须使用此方法，并且只能在这种情况下使用。该方法不适用于通过 URL 发送的外部内容。Macros 变量替换机制](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pages/#1-variable) 与此方法配合使用。

可以选择使用宏来包含内容：

如果您想在不对文档进行其他手动更改的情况下包含文档，请使用include Jinja 语法。
如果您在文档中包含了金雅 "块 "语法，则使用金雅 "扩展 "语法，该语法允许您覆盖或添加到特定部分。

拼写¶

我们使用 pyspelling 拼写检查程序。它在内核检查时运行。

当 pyspelling 识别出拼写错误的单词时，在大多数情况下，应在文档内容中予以修正。

在极少数情况下，如果它识别出的有效单词不在 "拼写 "字典中，您有两种选择：

如果是可能被多次重复使用的单词，则应按字母顺序将该单词添加到docs目录下的spelling_wordlist文档中。
如果是不太可能再次使用的单词，可以用 <nospell> / </nospell> 标记将其包裹起来，这样 pyspelling 就会在内联时忽略它。