AsciiDoc 标记语言

Fedora 文档团队 <https://discussion.fedoraproject.org/tag/docs-team> v1.0, 2022-12-10

本页面分享有关使用 AsciiDoc 进行编写的一般信息，以及 Fedora 文档中常见的 Fedora/Antora 特定语法。

AsciiDoc 基础知识

AsciiDoc 是一种轻量级标记语言，可用于以纯文本形式撰写笔记、文章、文档、书籍、网页、幻灯片以及手册页。

— asciidoctor.org

AsciiDoc 语法快速参考: AsciiDoc 标记的实用速查表。用它来速查，了解如何使用格式化、列表、媒体内容（图片和视频）、目录等。
AsciiDoc 推荐实践: 有关使用 AsciiDoc 撰写内容的最佳实践。最需要记住的一个实践就是每个句子应独占一行。

Fedora 文档片段

在编写 Fedora 文档时，有一些内容经常出现。但它们可能不会出现在一般的 AsciiDoc 文档中，比如在 asciidoctor.org 上。+ 本节包含了 Fedora 文档编写者可以方便地复制和粘贴到自己 AsciiDoc 文档中的实用参考。

内部链接

在本节中，我们将使用以下仓库结构作为示例：

文档仓库结构示例

📄 antora.yml (1)
📂 modules
  📂 ROOT
    📂 pages
      📄 index.adoc
      📄 another-page.adoc
      📂 sub-dir
        📄 rules.adoc
  📂 council
    📂 pages
      📄 guiding-policy.adoc

1	定义文档组件为 test-module（属性 `name`）

同仓库

使用相对于同一模块中 pages 目录的本地路径。

链接到根目录中的页面

xref:another-page.adoc

链接到 pages 子目录中的一个页面

xref:sub-dir/rules.adoc

同仓库，不同模块

类似于内部链接，但使用冒号（:）分隔模块名称。如果不确定是否需要使用此方法，通常是无需使用！在 Fedora 文档中，目前多个模块打包在同一仓库的情况并不常见。

示例 1

xref:council:guiding-policy.adoc

不同的仓库

链接到另一个 Fedora 文档页面，且该页面位于另一个仓库中。请注意，您必须使用另一个仓库中 antora.yml 文件中指定的 name 字段，否则链接将无法正常工作。如果目标模块名称是 ROOT，则可以省略模块名称，但仍需保留额外的冒号（:）。

示例 1，两个链接是等效的

xref:test-module::another-page.adoc
xref:test-module:ROOT:another-page.adoc

示例 2

xref:test-module:council:guiding-policy.adoc

URL 重定向

您可以通过使用 page-aliases 属性将旧页面重定向到新页面。语法与 xref links 相同。

示例 1。在 new-page.adoc 中

= 页面标题
:page-aliases: old-page.adoc

您也可以创建来自另一个模块或组件的重定向。

示例 2. new-page.adoc

= 页面标题
:page-aliases: test-module:council:removed-page.adoc

高亮语法

你可以通过设置源语言属性，为任何源代码块添加语法高亮。

为代码块设置源语言属性的示例

[,yaml]
----
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive
----

加入属性后代码块的渲染示例

output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

支持的语言列表可在 highlight.bundle.js in the Fedora Docs UI 中找到。

Datatables 数据表

你可以用 datatable role 属性将一个普通表格转换为 DataTables 。DataTables 提供筛选和排序功能。

定义 DataTable 的示例

|===
[.datatable]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%
|===

.Rendered DataTable [.datatable]
colA
colB
colC
colD
yyy
123
zzz
28%
bbb
242
aaa
42%
ddd
8874
yyy
99%
ccc
9
ttt
2%
aaa
987
www
18%

更多 DataTables 中可以使用的 roles 功能:

dt-search: 添加搜索框
dt-paging: 添加页码导航栏

你还可以利用 DataTables 内置的类来更改样式, 如显示 display 或 compact.

使用附加选项的示例

|===
[.datatable.dt-search.display]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
|===

Legal documentation 上可以看到 DataTables 的实际使用案例.

标签块

你可以创建一组标签,并用区块的方式来组织文档内容。

Example of defining a tab set [,asciidoc]

[tabs]
====
Tab A:: Contents of Tab A.

Tab B::
+
Contents of Tab B.

Tab C::
+
--
Contents of Tab C.

Contains more than one block.
--
====

Resulting tab set

Tab A
Tab B
Tab C

Contents of Tab A.

Contents of Tab B.

Contents of Tab C.

Contains more than one block.

有关标签的更多信息，请参阅 Asciidoctor 的 Tabs extension https://github.com/asciidoctor/asciidoctor-tabs 。

分页

If you have several pages that follow the same topic, you might be interested in enabling the pagination. + Pagination allows the reader to easily navigate to next and previous pages from the navigation tree by adding navigation links at the bottom of the page.

该选项可通过`page-pagination`属性启用。

= 页面标题
:page-pagination:

在本页你就可以看到一个活生生示例。

Button 和 Menu UI 宏

To keep consistency in presenting a button, keyboard bindings, or a menu item (path), Button and Menu UI Macros communicate to the reader what actions they need to take.

尽管该属性被标记为体验性功能，但 UI 宏已经是 AsciiDoc 的稳定功能，已经被采用编辑最新的 Quick Docs 系列文档。

该选项由实验属性启用。

= 页面标题
:experimental:

Button UI 宏的定义示例

. Click btn:[Create].

. Choose a passphrase that is strong but also easy to remember in the dialog that is displayed.

. Click btn:[OK] and the key is created.

Examples of defining Menu UI Macro

To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

Best practices

一些编写新页面或编辑现有页面时的几点建议。

文档标题

所有页面必须以一级标题开头。 [,asciidoc]

= 页面标题

Optionally, you can add authors and review metadata.

Example 1 - Authors and revision information

= 页面标题
Ben Cotton; Peter Boy; Petr Bokoc 2.0, 2022-11-26: fix for F37

You can decide to omit the version number, if you don’t need that information.

Example 2 - Revision information without version

= 页面标题
Francois Andrieu 2022-12-10: Added revision metadata example

While these metadata are optional, try to keep at least the revision date so readers know how up-to-date the page is.

Example 3 - Revision date only

= 页面标题
Fedora 文档团队 2022-12-10

Want to help? Learn how to contribute to Fedora Docs ›