| |
@@ -0,0 +1,85 @@
|
| |
+ = AsciiDoc markup
|
| |
+ Fedora Documentation Team <docs@lists.fedoraproject.org>
|
| |
+ v0.0.1, 2020-08-26
|
| |
+ :toc:
|
| |
+
|
| |
+ This page shares general information about writing in AsciiDoc as well as Fedora/Antora-specific syntax that comes up often in Fedora Documentation.
|
| |
+
|
| |
+
|
| |
+ [[basics]]
|
| |
+ == AsciiDoc basics
|
| |
+
|
| |
+ [quote,asciidoctor.org]
|
| |
+ ____
|
| |
+ AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text.
|
| |
+ ____
|
| |
+
|
| |
+ https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[*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.
|
| |
+
|
| |
+ https://asciidoctor.org/docs/asciidoc-recommended-practices/[*AsciiDoc Recommended Practices*]::
|
| |
+ Best practices about writing in AsciiDoc.
|
| |
+ Most importantly, note that https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[every sentence should be on its own line].
|
| |
+
|
| |
+
|
| |
+ [[snippets]]
|
| |
+ == 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.
|
| |
+
|
| |
+ [[internal-link]]
|
| |
+ === Link to a page in the same repository
|
| |
+
|
| |
+ Use the local path from the directory root to the AsciiDoc file name.
|
| |
+
|
| |
+ .Example 1
|
| |
+ [source,adoc]
|
| |
+ ----
|
| |
+ xref:page-name.adoc
|
| |
+ ----
|
| |
+
|
| |
+ .Example 2
|
| |
+ [source,adoc]
|
| |
+ ----
|
| |
+ xref:packaging/policy/rules.adoc
|
| |
+ ----
|
| |
+
|
| |
+ [[module-link]]
|
| |
+ === Link 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.
|
| |
+
|
| |
+ .Example 1
|
| |
+ [source,adoc]
|
| |
+ ----
|
| |
+ xref:module::page-name.adoc
|
| |
+ ----
|
| |
+
|
| |
+ .Example 2
|
| |
+ [source,adoc]
|
| |
+ ----
|
| |
+ xref:council:policy/guiding-policy.adoc
|
| |
+ ----
|
| |
+
|
| |
+ [[external-antora-link]]
|
| |
+ === Link 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.
|
| |
+
|
| |
+ .Example 1
|
| |
+ [source,adoc]
|
| |
+ ----
|
| |
+ xref:name:module:page-name.adoc
|
| |
+ ----
|
| |
+
|
| |
+ .Example 2
|
| |
+ [source,adoc]
|
| |
+ ----
|
| |
+ xref:council::code-of-conduct.adoc
|
| |
+ ----
|
| |
jflory7
commented 4 years ago
This is a first attempt at giving Fedora Documentation Writers a one-
stop location to get started writing AsciiDoc. Instead of trying to
rewrite existing documentation about AsciiDoc, I linked out to helpful
resources maintained by the
asciidoctor.orgupstream.However, this commit does write new documentation about handy snippets
to reuse in a Fedora-specific context. I also wrote a short guide on how
to use reusable attributes, since I realize this is something I have
done in many repositories I set up but never documented.
Part of #8 to improve the new contributor experience to Fedora
Documentation with AsciiDoc and Antora.