AsciiDoc 标记语言

Fedora 文档团队

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

AsciiDoc 基础知识

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

— asciidoctor.org
AsciiDoc 语法快速参考

Handy cheat sheet of what the AsciiDoc markup looks like. Use this for quick references and checking up on how to formatting, lists, media content (images and video), table of contents, and more.

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

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

Example 2. In new-page.adoc
= 页面标题
:page-aliases: test-module:council:removed-page.adoc

Syntax highlighting

You can add syntax highlighting to any source block by setting the source language attribute.

Example of setting the source language attribute to a code block
[,yaml]
----
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive
----
Example of rendered code block with such attribute
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

The list of supported languages can be found in the highlight.bundle.js in the Fedora Docs UI.

Datatables

You can convert a regular table to a DataTables using the datatable role attribute. DataTables provides filtering and ordering capabilities.

Example of defining a 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%

Additional roles can be used to add DataTables features:

  • dt-search: add search box

  • dt-paging: add pagination

You can also alter the styling with the help of built-in DataTables classes, such as display or compact.

Example of using additional options
|===
[.datatable.dt-search.display]
|colA | colB | colC | colD

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

DataTables real usage can be seen on the Legal documentation.

Tabs block

You can create a set of tabs to organize documentation content in a block.

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.

For more information about tabs, refer to the Asciidoctor Tabs extension at https://github.com/asciidoctor/asciidoctor-tabs.

Table of content

A table of content is automatically generated on the right of each pages.

There is no need to add the :toc: attribute as it will then add a duplicate table of content to the document.

The right-sided table of content only displays title levels up to level 2 by default. You can change this setting with the page-toclevels attribute.

= 页面标题
:page-toclevels: 3

Pagination

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.

This option is enabled by the page-pagination attribute.

= 页面标题
:page-pagination:

You can see a live example on this page.

Button and Menu UI macro

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.

Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc and used in latest Quick Docs edited.

This option is enabled by the experimental attribute.

= 页面标题
:experimental:

Examples of defining Button UI Macro

. 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

A few recommendation when writing a new pages, or editing an existing one.

Document header

All pages must start with a level 1 title. [,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 Documentation Team 2022-12-10

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