跳到内容

简介

本指南重点介绍了我们更高级的格式选项，包括警示、编号列表、表格等等。

文档可能需要也可能不需要包含任何这些元素。但是，如果您觉得您的文档将从特殊格式中受益，本指南应该会有所帮助。

关于标题的说明

标题不是特殊的格式字符；相反，它们是标准的 Markdown 语法。它们包含一个 **单一** 的一级标题

# This is Level one

以及任意数量的子标题值，二级到六级

## A Level 2 heading
### A Level 3 heading
#### A Level 4 heading
##### A Level 5 heading
###### A Level 6 heading

这里的关键是你可以根据需要使用任意数量的二级到六级标题，但只能使用 **一个** 一级标题。虽然文档在使用多个一级标题时看起来会是正确的，但文档右侧自动生成的目录 **不会** 在使用多个一级标题时正确显示（或者有时根本不显示）。在编写文档时请记住这一点。

关于支持的 HTML 元素的说明

在 Markdown 中技术上支持一些 HTML 元素。本文档中描述了其中一些元素，并且没有 Markdown 语法来替换它们。这些支持的 HTML 标签应该很少使用，因为 Markdown linter 会在文档中对它们提出警告。例如

  • 内联 HTML [元素名称]

如果您需要使用支持的 HTML 元素，请查看是否可以找到另一种方法来编写您的文档，而不会使用这些元素。如果您必须使用它们，仍然是允许的。

警示

警示是特殊的视觉“框”，允许您引起对重要事实的注意并突出显示它们。以下是警示类型

类型描述
note在蓝色框中显示文本
abstract在浅蓝色框中显示文本
info在蓝绿色框中显示文本
tip在蓝绿色框中显示文本（图标更偏绿色）
success在绿色框中显示文本
question在浅绿色框中显示文本
warning在橙色框中显示文本
failure在浅红色框中显示文本
danger在红色框中显示文本
bug在红色框中显示文本
example在紫色框中显示文本
quote在灰色框中显示文本
custom 1始终在蓝色框中显示文本
custom 2在所选类型的框的颜色中显示文本

如上面 custom 1 中所述，警示是无限的。在任何警示类型中添加自定义标题以获得所需的框颜色，如上面 custom 2 中所述。

始终以这种方式输入警示

!!! admonition_type "custom title if any"

    text of admonition

警示的正文文本必须从开始边距缩进四个 (4) 个空格。很容易看到它是哪里，因为它总是与警示类型的第一个字母对齐。标题和正文之间的额外行不会出现，但我们的翻译引擎 (Crowdin) 需要这些行才能正常运行。

以下是每种警示类型及其在文档中的显示方式的示例

Note

text

Abstract

text

Info

text

Tip

text

Success

text

Question

text

Warning

text

Failure

text

Danger

text

Custom

一个 custom1 类型。我们使用“custom”作为我们的警示类型。再次强调，这始终会在蓝色中呈现。

custom title

一个 custom2 类型。我们使用自定义标题修改了“warning”警示类型。以下是它的样子

!!! warning "custom title"

可扩展警示

如果警示包含非常长的内容，请考虑使用可扩展警示。它与常规警示具有相同的特征，但以三个问号而不是三个感叹号开头。所有其他警示规则都适用。可扩展警示如下所示

Warning Content

这是一个警告，内容不多。您可能想要为此使用常规警示，但是，这只是一个示例！

在您的编辑器中，它看起来像这样

??? 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 个空格等等）都适用于此内容。例如，文档可能需要针对不同的 Rocky Linux 版本提供不同的过程。在使用选项卡内容表示版本时，Rocky Linux 的最新版本应该排在最前面。在撰写本文时，该版本为 9.0

在 9.0 中执行此操作的过程

在 8.6 中执行此操作的过程

在您的编辑器中，它看起来像这样

=== "9.0"

    The procedure for doing this in 9.0

=== "8.6"

    The procedure for doing this in 8.6

请记住，该部分内部的所有内容必须继续使用 4 个空格缩进，直到该部分完成。这是一个非常方便的功能！

编号列表

编号列表看起来很容易创建和使用，一旦你掌握了它们，它们确实很容易。如果你只有一个简单的项目列表，没有复杂性，那么这种格式就足够了。

1. Item 1

2. Item 2

3. Item 3

  1. 项目 1

  2. 项目 2

  3. 项目 3

如果你需要在编号列表中添加代码块、多行，甚至文本段落，那么文本必须与你在注意中使用的缩进相同的四个（4）空格。

但是，你不能用眼睛将它们对齐在编号项目下方，因为这会差一个空格。如果你使用一个好的 Markdown 编辑器，你可以将你的制表符值设置为四个（4），这将使格式化所有内容变得更容易。

以下是一个多行编号列表的示例，其中包含一个代码块，以确保内容完整。

  1. 在处理包含代码块或其他元素的多行编号列表时，使用空格缩进来获得想要的结果。

    例如：这具有四个（4）空格的缩进，代表一个新的文本段落。此外，我们正在添加一个代码块。它也与我们的段落一样缩进了四个（4）空格。

    dnf update

  2. 这是我们的第二个列表项。由于你使用了四个（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 grey 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
```
````

是的，你刚刚看到的代码块在开头和结尾使用了五个反引号，以使其正确呈现。

抑制显示的提示和自动换行

在编写文档时，你可能希望在命令中显示一个提示，但又不想让用户在使用复制选项时复制该提示。这种情况的一个应用可能是编写实验室，你想要显示带有提示符的位置，如以下示例所示。

copy_option

如果按照正常格式显示，复制选项将复制提示符和命令，而复制仅命令更可取。为了解决这个问题，你可以使用以下语法来告诉复制选项你想要复制的内容。

``` { .sh data-copy="cd /usr/local" }
[root@localhost root] cd /usr/local
```

使用这种方法时，自动换行也会被抑制。

键盘

另一种尽可能增加文档清晰度的方法是表示在键盘上输入键的正确方式。在 Markdown 中，通过用双加号 (++) 将键或键包围起来来实现。用++key++ 完成。例如，要表示你必须在文档中按 Esc 键，可以使用++escape++。当你需要指示按多个键时，在它们之间添加一个+，就像这样：++ctrl+f4++。对于未定义的键（例如，我们正在指示一个未知的功能键，Fx 如下），将你的定义放在引号中 (++ctrl+"Fx"++)。如果需要同时按多个键，请在你的说明中添加“同时”或“同时”或类似的短语。以下是在你的编辑器中使用键盘说明的示例。

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 在物理终端之间切换。

本文件中接受的键盘命令列表 在此处。

Note

这些键盘快捷键始终使用小写字母输入，除非在引号中使用自定义键盘命令。

上标、下标和特殊符号

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 is H~2~0) 来输入下标，如前所述，下标在写作中并不常用。

用于引用的上标

你们中的一些人可能需要在编写文档时引用外部来源。如果你只有一个来源，你可以在结论中包含一个单一的链接，但如果你有多个来源1，你可以使用上标在你的文本2 中对其进行标记，然后在文档的末尾列出它们。请注意，引用的位置应该在“结论”部分之后。

在结论之后，你可以将你的标记包含在编号列表中以匹配上标，或者将它们输入为链接。这里显示了两个示例。

  1. "How Multiples Are Used In Text" by Wordy W. McWords https://site1.com
  2. "Using Superscript In Text" by Sam B. Supersecret https://site2.com

或者

1 "How Multiples Are Used In Text" by Wordy W. McWords
2 "Using Superscript In Text" 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==. Highlighting is handled by surrounding the text with `==`.

组合不同的格式类型

Rocky 文档在将多个元素组合到另一个元素中时提供了一些优雅的格式选项。例如，带编号列表的注意。

Note

当你将事物组合在一起时，事情可能会变得有些混乱。比如当

  1. 你在注意中添加一个编号选项列表。

  2. 或者你添加一个包含多个代码块的编号列表。

    dnf install some-great-package

    它也位于多段落编号列表中。

或者你可能有一个编号列表，其中包含一个额外的注意。

  1. 此项非常重要。

    在这里，你正在向列表项添加一个键盘命令。

    按下 Esc 没有任何特殊原因。

  2. 但此项非常重要，并且包含多个段落。

    它在中间有一个注意。

    Warning

    在不同的格式类型中使用多个元素，事情可能会变得很混乱！

如果你跟踪用于缩进和分隔这些项目的四个（4）空格的魔法，它们将以你想要的方式逻辑地显示。有时这真的很重要。

你甚至可以在另一个元素中嵌入表格或块引用（实际上是任何格式元素类型）。在这里，你有一个编号列表、一个注意、一个表格和一些块引用元素，它们全部捆绑在一起。

  1. 当你使用多个元素时，尝试跟上你文档中的所有内容可能是一项真正的任务。

  2. 如果你感到不知所措，请考虑

    重要：我认为我的大脑很痛！

    当组合多个格式元素时，你的大脑可能会有点混乱。在开始之前，请考虑多摄入一些咖啡因！

    类型每日咖啡因摄入量
    茶它最终会让你到达目的地。
    咖啡适合挑剔的味蕾。
    红牛味道很糟糕 - 但它会让你保持活力！
    山露过度炒作

    糖 如果你不喜欢咖啡因

    忍受 如果其他方法都失败了，请更专注

  3. 存在许多例子，但以上说明了可以在其中嵌套所有内容。只需记住四个（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 中添加一个注释，这些注释在渲染时不会显示。这有许多原因。例如，如果你想要为稍后将要添加的内容添加占位符，你可以使用注释来标记你的位置。

在 Markdown 中添加注释的最佳方法是在两个正斜杠 "//" 周围使用方括号 "[]"，后跟一个冒号和内容。它将看起来像这样。

[//]: This is a comment to be replaced later

注释之前和之后应该有一个空行。

更多阅读

结论

使用标题、警示框、表格、编号列表和引用块格式化文档可以提高文档的清晰度。在使用警示框时，请务必选择正确的类型。这样可以更容易地直观地识别特定警示框的重要性。

您**不必**使用高级格式选项。过度使用特殊元素会导致不必要的混乱。学会适度且恰当地使用这些格式元素可以非常有助于在文档中表达您的观点。

最后，为了使格式化更容易，请考虑将 Markdown 编辑器的 TAB 值更改为四个（4）空格。

作者：Steven Spencer

贡献者：tianci li、Ezequiel Bruni、Krista Burdine、Ganna Zhyrnova