文档格式
简介¶
本指南重点介绍了我们更高级的格式选项，包括提醒、编号列表、表格等。
文档可能需要也可能不需要包含这些元素。但是，如果您认为您的文档将受益于特殊格式，本指南应该会有所帮助。
关于标题的说明
标题不是特殊的格式字符；而是标准的 markdown 语法。它们包括一个单个一级标题
# This is Level one
以及任意数量的子标题，级别 2 到 6
## A Level 2 heading
### A Level 3 heading
#### A Level 4 heading
##### A Level 5 heading
###### A Level 6 heading
关键在于，您可以使用任意数量的 2 到 6 级标题，但只能使用一个一级标题。虽然文档会显示为正确，但文档的自动生成的目录（显示在右侧）在超过一个一级标题时将不会正确显示（有时根本不显示）。在撰写文档时请牢记这一点。
关于一级标题的另一个重要说明：如果使用了 title: 元信息，那么这将是一级标题。您不应再添加一个。例如，本文档的标题元信息是
---
title: Document Formatting
因此，添加的第一个标题是“Introduction”，级别为 2。
## Introduction
关于支持的 HTML 元素的说明
有些 HTML 元素在 markdown 中技术上是支持的。其中一些在本文件中进行了描述，并且没有 markdown 语法可以替换它们。这些支持的 HTML 标签应该很少使用，因为 markdown linter 会在文档中抱怨它们。例如
- 行内 HTML [元素名称]
如果您需要使用受支持的 HTML 元素，请查看是否能找到另一种不使用这些元素的方法来编写文档。如果您必须使用它们，仍然允许。
关于链接的说明
链接不是特殊的格式，而是引用其他文档（内部链接）或外部网页的标准方法。但是，在为 Rocky Linux 撰写文档时，有一种特殊类型的链接您不应使用，那就是锚点，或指向同一文档中某个位置的链接。
锚点在 Rocky Linux 的源语言（英语）中工作，但一旦通过我们的 Crowdin 界面进行翻译，它们在那些语言中就会失效。这是因为 markdown 中一个不包含 HTML 元素的可用锚点，会使用标题来创建链接
## A Header
Some text
A Link to [that header](#-a-header)
通过将鼠标悬停在已创建文档中的永久链接上，可以找到此链接，但本质上是标题加上“#”以及小写的标题，用破折号 (-) 分隔。
但是，当文档被翻译时，标题会被翻译，但链接却超出了 Crowdin 允许翻译的范围，因此它仍然是原始的（英文）状态。
如果您需要使用锚点，请查看您的文档，看看内容重组是否可以使该锚点变得不必要。只需知道，如果您在新撰写的文档中使用锚点，一旦该文档被翻译，该锚点就会失效。
提醒¶
提醒是特殊的视觉“框”，用于吸引对重要事实的注意并突出它们。以下是提醒的类型
| 类型 | 描述 |
|---|---|
| 注意 | 以蓝色框显示文本 |
| 摘要 | 以浅蓝色框显示文本 |
| 信息 | 以蓝绿色框显示文本 |
| 技巧 | 以蓝绿色框显示文本（图标略绿） |
| 成功 | 以绿色框显示文本 |
| 问题 | 以浅绿色框显示文本 |
| 警告 | 以橙色框显示文本 |
| 失败 | 以浅红色框显示文本 |
| 危险 | 以红色框显示文本 |
| 错误 | 以红色框显示文本 |
| 示例 | 以紫色框显示文本 |
| 引用 | 以灰色框显示文本 |
| 自定义 1 | 始终以蓝色框显示文本 |
| 自定义 2 | 以所选类型框的颜色显示文本 |
如上面自定义 1 所述，提醒是无限的。为任何提醒类型添加自定义标题，以获得特定提醒所需的框颜色，如上面自定义 2 所述。
提醒总是这样输入的
!!! admonition_type "custom title if any"
text of admonition
提醒的正文必须比起始边距缩进四个（4）空格。很容易看到这一点，因为它总是会与提醒类型的第一个字母对齐。标题和正文之间的额外行不会出现，但我们的翻译引擎（Crowdin）需要这些才能正常工作。
以下是每种提醒类型的示例及其在文档中的外观
注意
文本
摘要
文本
信息
文本
技巧
文本
成功
文本
问题
文本
警告
文本
失败
文本
危险
文本
自定义
一个自定义1类型。我们将“custom”用作我们的提醒类型。再次强调，这始终会呈现为蓝色。
自定义标题
一个自定义2类型。我们修改了“warning”提醒类型，并添加了自定义标题。这是它的样子
!!! warning "custom title"
可展开的提醒¶
如果提醒内容非常长，请考虑使用可展开的提醒。它具有与普通提醒相同的特性，但以三个问号开头，而不是三个感叹号。所有其他提醒规则均适用。可展开的提醒看起来像这样
警告内容
这是一个警告，内容不多。您本可以使用普通提醒，但嘿，这只是一个例子！
这在您的编辑器中看起来像这样
??? warning "Warning Content"
This is a warning, with not very much content. You would want to use a regular admonition for this, but Hey, this is just an example!
文档中的标签页内容¶
格式化标签页内容类似于提醒。它以三个等号开头，而不是三个感叹号或问号。所有提醒格式（4 个空格等）都适用于此内容。例如，文档可能需要不同的过程，具体取决于操作系统是如何安装的。随着文档版本控制的实施，不应有必要使用标签页内容格式来区分完整的版本内容（例如，9.6 和 8.10）。
如果您的安装是通过完整的操作系统或 Live 镜像完成的，请使用此过程。
如果您的操作系统安装使用的是最小 ISO，请使用此过程。
这在您的编辑器中看起来像这样
=== "9"
Use this procedure if your installation was by way of the full operating system, or from a Live image.
=== "9-minimal"
Use this procedure if your operating system installation was with the minimal ISO.
请记住，部分中的所有内容必须继续使用 4 个空格缩进，直到部分完成。这是一个非常方便的功能！
编号列表¶
编号列表听起来很容易创建和使用，一旦您掌握了它们，它们就很方便。如果您只有一个项目列表而没有复杂性，那么这种格式效果很好
1. Item 1
2. Item 2
3. Item 3
-
项目 1
-
项目 2
-
项目 3
如果您需要向编号列表添加代码块、多行文本甚至段落，则文本必须与您在提醒中使用的缩进具有相同的四个（4）空格。
但是，您不能用眼睛来对齐它们，因为这会偏离一个空格。如果您使用好的 markdown 编辑器，您可以将制表符设置为四个（4）空格，从而使所有格式化更容易。
以下是一个多行编号列表的示例，其中包含一个代码块
-
处理包含代码块或其他元素的多个编号列表时，请使用空格缩进来获得您想要的结果。
例如：这具有四个（4）空格缩进，代表一个新段落。此外，我们还添加了一个代码块。它也与我们的段落一样，缩进了相同的四个（4）空格
dnf update -
这是我们的第二个列表项。因为您使用了四个（4）空格缩进（上面），所以它会以下一个编号序列（2）呈现。如果您在后续段落和代码中输入的项目 1 没有缩进，那么它会再次显示为项目 1，这不是您想要的。
以下是原始文本的样子
1. When dealing with multi-line numbered lists that include code blocks or other elements, use the space indentation to get what you want.
For example: this has the four (4) space indentation and represents a new paragraph of text. In addition, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph:
```bash
dnf update
```
2. Here is our second listed item. Because you used the four (4) space indentation (above), it renders with the next sequence of numbering (2), but if you had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what you want.
表格¶
在上面的例子中，表格帮助我们布局命令选项或提醒类型和描述。这显示了提醒部分中表格的输入
| type | Description |
|-----------|------------------------------------------------------------|
| note | displays text in a blue box |
| abstract | displays text in a light blue box |
| info | displays text in a blue-green box |
| tip | displays text in a blue-green box (icon slightly greener) |
| success | displays text in a green box |
| question | displays text in a light green box |
| warning | displays text in an orange box |
| failure | displays text in a light red box |
| danger | displays text in a red box |
| bug | displays text in a red box |
| example | displays text in a purple box |
| quote | displays text in a gray box |
| custom^1^ | always displays text in a blue box |
| custom^2^ | displays text in a box with the color of the chosen type |
请注意，不必将每列按大小细分（就像我们在表格的第一部分所做的那样），但在 markdown 源文件中这样做会更具可读性。当您将项目串联在一起时，可能会感到困惑，只需在表格的最后一项中看到的管道字符 "|" 处断开列。
块引用¶
块引用用于引用其他来源的文本并将其包含在您的文档中。markdown 中块引用的示例包括
> **an item** - A description of that item
followed by:
> **another item** - Another description of that item
如果您要将两个引用放在一起，则需要用其他单词分隔它们，以避免生成 markdown 错误（如上所示）。
页面显示时，这看起来像这样
一个项目 - 该项目的描述
之后是
另一个项目 - 另一个项目的描述
行内和块级代码块¶
我们处理代码块的方法很简单。如果您的代码足够短，您可以在句子中使用它（并且想使用它），就像您刚才看到的那样，请使用单个反引号 `
A sentence with a `command of your choosing` in it.
不在文本段落内使用的任何命令（尤其是多行长代码）都应为完整的代码块，用三重反引号 ``` 定义
```bash
sudo dnf install the-kitchen-sink
```
那种格式的 bash 部分是 markdown 推荐的代码标识符，但可以帮助进行语法高亮。如果您展示文本、Python、PHP、Ruby、HTML、CSS 或任何其他代码，则“bash”将更改为您使用的语言。
顺便说一句，如果您需要在代码块内显示代码块，请在父块中添加一个更多的反引号 `
````markdown
```bash
sudo dnf install the-kitchen-sink
```
````
是的，您刚才看到的代码块开头和结尾使用了五个反引号才能正确渲染。
抑制显示的提示符和自动换行¶
有时在编写文档时，您可能希望在命令中显示提示符，但又不希望用户在复制时复制该提示符。例如，编写实验课时，您可能希望显示带有提示符的位置，如下例
如果正常格式化，复制选项将复制提示符和命令，而只复制命令是更好的选择。要解决此问题，您可以使用以下语法来告诉复制选项您想要复制的内容
``` { .sh data-copy="cd /usr/local" }
[root@localhost root] cd /usr/local
```
使用此方法时，还会抑制自动换行。
键盘¶
使您的文档尽可能清晰的另一种方法是正确表示在键盘上输入键的方式。在 markdown 中，通过将键或键用双加号 (++) 包围来实现。使用 ++key++ 进行此操作。例如，要在文档中表示需要按 Escape 键，您将使用 ++escape++。当您需要指示按下多个键时，请在它们之间添加一个 +，如下所示：++ctrl+f4++。对于未定义的键（例如，我们在下面指示一个神秘的功能键 Fx），请将您的定义放在引号中（++ctrl+"Fx"++）。如果需要同时按下键，请在您的说明中添加“simultaneously”或“at the same time”或类似的短语。以下是在您的编辑器中显示键盘指令的示例
A workstation-type installation (with a graphical interface) starts this interface on terminal 1. Linux being multi-user, it is possible to connect several users several times, on different **physical terminals** (TTY) or **virtual terminals** (PTS). Virtual terminals are available within a graphical environment. A user switches from one physical terminal to another using ++alt+"Fx"++ from the command line or ++ctrl+alt+"Fx"++.
以下是显示时的样子
工作站类型的安装（带有图形界面）在终端 1 上启动此界面。Linux 是多用户系统，可以连接多个用户多次，在不同的物理终端（TTY）或虚拟终端（PTS）上。虚拟终端在图形环境内可用。用户可以使用 Alt+Fx 从命令行切换到不同的物理终端，或使用 Ctrl+Alt+Fx 切换。
接受的键盘命令列表 在此文档中。
注意
这些键盘快捷键始终以小写字母输入，除非在引号内使用了自定义键盘命令。
强制换行¶
有时，简单的 Enter 键在 markdown 中不会产生新行。当项目符号项使用大量格式字符时，有时会发生这种情况。您可能还希望添加换行符以更好地格式化文本。在这些情况下，您需要在想要换行的地方的行末添加两个空格。由于在某些 markdown 编辑器中空格不可见，因此此示例显示了输入的空格
- 带有额外格式的项目符号 Space+Space
- 另一个项目
上标、下标和特殊符号¶
Rocky Linux 文档支持上标和下标符号，使用 ^ 表示上标，使用 ~ 表示下标。上标将标签之间的文本放置在正常文本的稍上方，而下标将文本放置在稍下方。上标是这两种中最常用的。一些特殊字符本身就显示为上标，无需添加标签，但您也可以结合使用标签来改变这些字符的方向，如下面的版权符号所示。您可以使用上标来
- 表示序数词，例如 1st、2nd、3rd
- 版权和商标符号，如 ©、TM 或 ™、®&
- 作为引用的标记，例如 this1、this2 和 this3
一些特殊字符，如 ©，通常不是上标，而另一些，如 ™，是。
以下是所有上述内容在 markdown 代码中的样子
* represent ordinal numbers, such as 1^st^, 2^nd^, 3^rd^
* copyright and trademark symbols, like ^©^, ^TM^ or ^™^, ^®^
* as notation for references, such as this^1^, this^2^ and this^3^
Some special characters, such as © are not normally superscript, while others such as ™, are.
要强制上标，请用 ^ 包围您想要上标的内容。
通过用 ~ 标签包围您的文本来输入下标（H20 是 H~2~0），如前所述，在写作中不常用。
用于引用的上标¶
您中的一些人可能需要在撰写文档时引用外部来源。如果您只有一个来源，您可以将其包含在结论中作为单个链接，但如果您有多个来源1，您可以使用上标在文本中注明2，然后在文档末尾列出它们。请注意，引用的位置应在“结论”部分之后。
在结论之后，您可以将您的注释放在编号列表中以匹配上标，或将它们作为链接输入。此处显示了两种示例
- “文本中多重用法” by Wordy W. McWords https://site1.com
- “文本中使用上标” by Sam B. Supersecret https://site2.com
或
1 “文本中多重用法” by Wordy W. McWords
2 “文本中使用上标” by Sam B. Supersecret
以下是所有这些在您的编辑器中的样子
1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com)
2. "Using Superscript In Text" by Sam B. Supersecret [https://site2.com](https://site2.com)
or
[1](https://site1.com) "How Multiples Are Used In Text" by Wordy W. McWords
[2](https://site2.com) "Using Superscript In Text" by Sam B. Supersecret
突出显示文本¶
另一种增强文档的方法是使用突出显示。您可以通过用 == 包围文本来使用突出显示。
这在您的编辑器中看起来像这样
Another possible way to enhance documentation is with ==highlighting==. You can use highlighting by surrounding the text with `==`.
组合不同格式¶
Rocky 文档在将多个元素组合在另一个元素内时提供了一些优雅的格式选项。例如，带有编号列表的提醒
注意
组合事物时事情可能会变得有点疯狂。例如，当
-
您在提醒中添加了选项的编号列表
-
或者您添加了带有多个代码块的编号列表
dnf install some-great-package这也包含在多段落编号列表中。
或者您可能有一个编号列表，附加一个提醒
-
此项目非常重要
在此处，您将键盘命令添加到列表项中
按 Esc 无特别原因。
-
但这个项目非常重要并且有多个段落
并且它中间有一个提醒
警告
当组合多个格式元素时，事情可能会变得有点疯狂！
如果您能记住神奇的四个（4）空格来缩进和分隔这些项目，它们将显示得合乎逻辑并且完全符合您的期望。有时这真的很重要。
您甚至可以将表格或块引用（实际上是任何格式化项目类型）嵌入到另一个之中。在这里，您将编号列表、提醒、表格和一些块引用元素捆绑在一起
-
处理多个元素时，尝试跟上文档中发生的一切可能是一项艰巨的任务。
-
如果您感到不知所措，请考虑
重要：我觉得我的大脑要痛了！
组合多个格式元素时，您的大脑可能会有点疯狂。开始之前，请考虑多喝些咖啡因！
类型 咖啡因每日摄入量 茶 最终会起作用 咖啡 为有品位的味蕾 红牛 味道很糟糕——但它能让你继续前进！ 激浪 被过度炒作 糖 如果咖啡因不合您口味
忍受 如果其他方法都失败了，多集中注意力
-
存在许多示例，但上面的例子说明了将所有内容嵌套在其中的可能性。只需记住这四个（4）个神奇的空格。
以下是这个例子在您的编辑器中的样子
As long as you keep track of the magic four (4) spaces to separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important.
You can even embed a table or block quote (literally any formatting item type) within another one. Here have a numbered list, an admonition, a table, and some block quote elements all bundled together:
1. Trying to keep up with everything that is going on in your document can be a real task when working with multiple elements.
2. If you are feeling overwhelmed, consider:
!!! warning "important: I think my brain hurts!"
When combining multiple formatting elements, your brain can go a little crazy. Consider sucking down some extra caffeine before you begin!
| type | caffeine daily allowance |
|-----------------|----------------------------------|
| tea | it will get you there eventually |
| coffee | for discerning taste buds |
| red bull | tastes terrible - but it will keep you going! |
| mountain dew | over hyped |
> **sugar** if caffeine is not to your liking
> **suffer** if all else fails, concentrate more
3. Many examples exist, but the above illustrates that it is possible to nest everything within. Just remember the four (4) magic spaces.
不可显示字符¶
markdown 中有些字符将无法正确显示。有时是因为这些字符是 HTML 或其他标签类型（例如链接）。在撰写文档时，有时您需要显示这些字符才能说明您的观点。显示这些字符的规则是转义它们。下面是一个包含这些不可显示字符的表，后面是一个显示表格代码的代码块。
| 符号 | 描述 |
|---|---|
| \ | 反斜杠（用于转义） |
| ` | 反引号（用于代码块） |
| * | 星号（用于项目符号） |
| _ | 下划线 |
| { } | 花括号 |
| [ ] | 方括号（用于链接标题） |
| < > | 尖括号（用于直接 HTML） |
| ( ) | 圆括号（用于链接内容） |
| # | 井号（用于 markdown 标题） |
| | | 管道符（用于表格） |
| + | 加号（用于表格） |
| - | 减号或连字符（用于表格和项目符号） |
| ! | 感叹号（用于提醒和表格） |
代码中的表格是
| symbol | description |
|-------------|---------------------------------------------------|
| \\ | backslash (used for escaping) |
| \` | backtick (used for code blocks) |
| \* | asterisk (used for bullets) |
| \_ | underscore |
| \{ \} | curly braces |
| \[ \] | brackets (used for link titles) |
| < > | angle brackets (used for direct HTML) |
| \( \) | parentheses (used for link content) |
| \# | pound sign (used for markdown headers) |
| | | pipe (used in tables) |
| + | plus sign (used in tables) |
| - | minus sign or hyphen (used in tables and bullets) |
| ! | exclamation (used in admonitions and tables) |
最后的代码显示，某些字符在表格中使用时需要其 HTML 字符代码。
在实际文本中，您将转义字符。例如，\| 将显示管道符号，\> 将显示尖括号符号，\+ 将显示加号，\- 将显示减号，\! 将显示感叹号。
您可以从这句话中删除反引号来查看
在实际文本中，您将转义字符。例如，| 将显示管道符号，> 将显示尖括号符号，+ 将显示加号，- 将显示减号，! 将显示感叹号。
最后一项 - 注释¶
有时，您可能想在 markdown 中添加一个注释，该注释在渲染时不会显示。原因有很多。如果您想为稍后添加的内容添加一个占位符，您可以使用注释来标记您的位置。
在 markdown 中添加注释的最佳方法是使用方括号“[]”括住两个正斜杠“//”，后面跟着一个冒号和内容。这看起来像这样
[//]: This is a comment to be replaced later
注释前后应留有空行。
更多阅读¶
结论¶
带有标题、提醒、表格、编号列表和块引用的文档格式可以为您的文档增加清晰度。使用提醒时，请仔细选择正确的类型。这可以更容易地在视觉上看到特定提醒的重要性。
您不必必须使用高级格式选项。过度使用特殊元素可能会导致混乱。学会保守地、熟练地使用这些格式项目可以非常有帮助，以在文档中传达您的观点。
最后，为了使格式化更容易，请考虑将您的 markdown 编辑器的 TAB 值更改为四个（4）空格。
作者：Steven Spencer
贡献者：tianci li, Ezequiel Bruni, Krista Burdine, Ganna Zhyrnova