This page shares general information about writing in AsciiDoc as well as Fedora/Antora-specific syntax that comes up often in Fedora Documentation.
AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text.
- 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
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:
📄 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
Use the local path relative to the
pages directory in the same module.
Same repository, different module
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.
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 (
You can create a redirect from an old page to a new one by using the
The syntax is the same as for xref links.
= Page Title :page-aliases: old-page.adoc
You can also create a redirect from another module or component.
= Page Title :page-aliases: test-module:council:removed-page.adoc
You can add syntax highlighting to any source block by setting the source language attribute.
[,yaml] ---- output: clean: true dir: ./public destinations: - provider: archive ----
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.
You can convert a regular table to a DataTables using the
datatable role attribute.
DataTables provides filtering and ordering capabilities.
[.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
[.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.
Table of content
A table of content is automatically generated on the right of each pages.
There is no need to add the
The right-sided table of content only displays title levels up to level 2 by default.
You can change this setting with the
= Page Title :page-toclevels: 3
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 Title :page-pagination:
You can see a live example on this page.
A few recommendation when writing a new pages, or editing an existing one.
All pages must start with a level 1 title.
= Page Title
= 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.
= 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.
= Page Title Fedora Documentation Team 2022-12-10
Want to help? Learn how to contribute to Fedora Docs ›