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.
- 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.
Link to a page in the same repository
Use the local path from the directory root to the AsciiDoc file name.
xref:page-name.adocxref:packaging/policy/rules.adocLink to a page in the same repository, but 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.
xref:module:page-name.adocxref:council:policy/guiding-policy.adocLink to a page in a different Fedora Documentation repository
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.
xref:name:module:page-name.adocxref:council::code-of-conduct.adoc