AsciiDoc markup

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.

Use the local path from the directory root to the AsciiDoc file name.

Example 1
xref:page-name.adoc
Example 2
xref:packaging/policy/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:module::page-name.adoc
Example 2
xref:council:policy/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.

Example 1
xref:name:module:page-name.adoc
Example 2
xref:council::code-of-conduct.adoc