AsciiDoc markup

Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs> v1.0, 2022-12-10

This page shares general information about writing in AsciiDoc as well as Fedora/Antora-specific syntax that comes up often in Fedora Documentation.

AsciiDoc basics

AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text.

— asciidoctor.org
AsciiDoc Syntax Quick Reference

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 Recommended Practices

Best practices about writing in AsciiDoc. Most importantly, note that every sentence should be on its own line.

Fedora Documentation snippets

When you write Fedora Documentation, some things come up frequently. They may not be documented in general AsciiDoc documentation, like on asciidoctor.org. + This section contains handy references for Fedora Documentation writers to copy and paste in their own AsciiDoc documents.

In this section, we will use the following repository structure as an example:

Example of documentation repository structure
📄 antora.yml (1)
📂 modules
  📂 ROOT
    📂 pages
      📄 index.adoc
      📄 another-page.adoc
      📂 sub-dir
        📄 rules.adoc
  📂 council
    📂 pages
      📄 guiding-policy.adoc
1 Defines the documentation component as test-module (attribute name)

Same repository

Use the local path relative to the pages directory in the same module.

Link to a page at the root level
xref:another-page.adoc
Link to a page in a subdirectory of pages
xref:sub-dir/rules.adoc

Like an internal link, but use a colon (:) to separate the module name. If you are not sure if you need this, you likely don’t! Multiple modules bundled in the same repository is not currently a common scenario in Fedora Documentation.

Example 1
xref:council:guiding-policy.adoc

Link to another Fedora Documentation page that exists in another repository. Note that you must use the name field specified in the antora.yml file in the other repository or it will not work. In case the target module name is ROOT, you can omit the name but you still need the extra colon (:).

Example 1, both links are equivalent
xref:test-module::another-page.adoc
xref:test-module:ROOT:another-page.adoc
Example 2
xref:test-module:council:guiding-policy.adoc

URL redirects

You can create a redirect from an old page to a new one by using the page-aliases attribute. The syntax is the same as for xref links.

Example 1. In new-page.adoc
= Page Title
:page-aliases: old-page.adoc

You can also create a redirect from another module or component.

Example 2. In new-page.adoc
= Page Title
: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 Title
: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 Title
: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.

= Page Title
: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]

= Page Title

Optionally, you can add authors and review metadata.

Example 1 - Authors and revision information
= Page Title
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
= Page Title
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
= Page Title
Fedora Documentation Team 2022-12-10

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