This page gives contributors a quick overview of tips and best practices for writing in AsciiDoc. It is for sure not complete nor covers all possibilities, but gives a quick reference for common used writing and formatting tasks. For a complete reference see the Asciidoctor Documentation.
Table of Contents
- Initial Reading
- File Locations
- Links
- Images
- Include
- Code Blocks
- Literal Text and Blocks
- Admonition
- Air Quotes
- Preserve Line Breaks
- Text Formatting
- Keyboard Shortcuts and UI Button Text
- Menu Selections
- Lists
- Headers, Titles, Sections and Anchors
- Tables
- Comments
Here is a good starting point to get a quick Antora overview Three Core Antora Concepts
- All documents are written into the directory
modules/module_name/pages/<path> - All images are written into the directory
modules/module_name/assets/images/<path> - All examples are written into the directory
modules/module_name/examples/<path>
When using paths to include, you might need to use the module_name when linking to another module,
but you must not use pages, assets/images or examples as the path component, only <path>.
See the examples in the relevant sections.
In a nutshell, there are two kind of links.
- External links (referencing content outside the documentation)
- Internal links (referencing content inside the documentation)
Reference: Links
A link follows this style: http(s)://domain/#section[Printed Name]
Where #section and [Printed Name] are optional components.
The link: prefix is only needed when the target is not a URI. That's because the URI protocol is an implicit
macro (in other words, http(s): is recognized as a macro prefix of an implicit link).
Example: https://github.com/owncloud-docker/server#launch-with-plain-docker[in the GitHub repository]
A URL may not display correctly when it contains characters such as underscores (_) or carets (^) Please see Troubleshooting Complex URLs how to solve that.
This is an example of an URL containing problematic characters which needs special treatment:
https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)
Prefix: xref:
Reference: Cross Reference
In a nutshell, an internal link called Cross Reference can link to
- a documentation file
- a section title inside a documentation file
- a reference to an anchor set inside a documentation file
All referencable content must be inside the directory structure of modules/.
An xref is written in following example style: xref:module_name:<path>/file.adoc#section[Printed Name]
Where module_name:, #section and [Printed Name] are optional components.
module_name: is mandatory when referenced content is not in the same module.
<path> is the path to your referenced file.
You can reference a section or an anchor inside the same file, another file - even in another module.
Example: xref:configuration/server/occ_command.adoc#apps-commands[the Market app]
Prefix: image
Reference: Images
All images have to be stored in a path under modules/module_name/assets/images/<path>
An image is written in following example style: image:<path>/image_name[Alternative Image Text]
Example: image:configuration/files/encryption1.png[Encryption]
IMPORTANT Please be advised, in case you use an Alternative Image Text, not to use double quotes to highlight some text elements. Double quotes will be rendered properly when the html documentation is built, but creating the pdf will return a warning that the string can not be parsed and the complete image link is broken. You can avoid that by using single quotes and ticks (not backticks!) instead.
Bad:
image:enterprise/firewall/firewall-3.png[Protecting files tagged with "Confidential" from outside access]
Good:
image:enterprise/firewall/firewall-3.png[Protecting files tagged with 'Confidential' from outside access]
Prefix: include
Reference: Include
The include directive provides a way to import content from another file into the current document.
An include is written in following example style: include::<path>/file[<attrlist>]
When using asciidoc files to include, the <attrlist> option contains as example the leveloffset=+1 to correct the level offset of the file included.
You can include example files like scripts or include documentation files. Both types are used to make the raw documentation files easier to read and to maintain.
When creating example files, these files must be saved into a path of the examples directory: module_name/examples
Example:
include::{examplesdir}/installation/post-installation-steps.sh[]
( {examplesdir} will be resolved by the build process automatically)
If you include a standard page (a page that is stored in the pages directory) into another page, you must set the page-partial AsciiDoc attribute in the document header of the page being included.
= The Page to be Included
:page-partial:
Page contents.
Example:
include::encryption-types.adoc[leveloffset=+1]
(the including file in this example is in the same directory as the included file)
Reference: Listing and source code blocks
Reference: Building blocks in AsciiDoc
[source, <language>]
----
text
text
----
Optional define the <language>
Example:
[source,console]
----
subscription-manager repos --enable rhel-server-rhscl-7-rpms
----
You can also use include in code blocks to include an example.
Example:
[source,console]
----
include::{examplesdir}/installation/post-installation-steps.sh[]
----
Reference: Literal Text and Blocks
Literal paragraphs and blocks display the text you write exactly as you enter it. Literal text is treated as pre-formatted text.
Example:
....
Checking system health.
- file permissions are ok.
....
Reference: Admonitions
Reference: Admonition blocks
An admonition paragraph is rendered in a callout box with the admonition label — or its corresponding icon — in the gutter.
Asciidoctor provides five admonition style labels: NOTE, TIP, IMPORTANT, CAUTION and WARNING
Use this way when you just have to write text.
A simple admonition is written in the following style: <label>: Text
Example:
NOTE: If you have a large ownCloud installation and have
shell access, you should ...
A complex admonition can contain special formatting, tables, lists, literal text and blocks
and is written in the following style, where ==== define the begin/end of the admonition block:
[<label>]
====
your complex text
====
Example:
[TIP]
====
We strongly encourage you to put your server in single user mode
before setting up encryption.
To do so, run the following command:
....
sudo -u www-data php occ maintenance:singleuser --on
....
====
Reference: Air Quotes
If you want to quote sentences or statements but not using an admonition, you can use air quotes. Air quotes are two double quotes on each line, emulating the gesture of making quote marks with two fingers on each hand.
Example:
""
Not everything that is faced can be changed.
But nothing can be changed until it is faced.
""
Reference: Line Breaks
Since adjacent lines of text are combined into a single paragraph, you can wrap paragraph text or put each sentence or phrase on a separate line. The line breaks won’t appear in the output.
If you want the line breaks preserved, use a space followed by the plus sign +.
You can use this method also in tables or lists.
Example:
This is the first line, +
This is the next line separated by a line break.
Reference: Text Formatting
There are various ways to emphasize text.
You can use styles like bold, italic, etc respectively quote text.
If you want to print a tick or backtick etc as it is, you must escape it.
Please see the reference link for more details.
Reference: Keyboard Shortcuts
Reference: UI buttonss
You can create a button styled text like you want a user to press specific keyboard button(s) or browser text buttons.
The syntax for keyboard shortcuts is: kbd:[key(+key)*]
The syntax for UI button text is: btn:[text]
Examples:
kbd:[F11]
kbd:[Ctrl+T]
kbd:[Ctrl+Shift+N]
kbd:[Show disabled apps]
btn:[OK]
btn:[Open]
Reference: Menu Selections
Trying to explain to someone how to select a menu item can be a pain. With the menu macro, the symbols do the work.
The syntax for this is: menu:start[next > next > *]
Example:
Go to menu:Settings[Admin > Apps] and click on kbd:[Show disabled apps]
Reference: Unordered Lists
To create a list, use the * sign.
You can give your list a title by adding on top of the list a . directly followed by the text without a space.
If you want to nest your list, use multiple * stars according the nesting level.
When items contain more than one line of text, leave a blank line before the next item to make the list easier to read.
If you want to add additional paragraphs or other block elements, see List Continuation for more details.
Example:
.List Title
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
Reference: Header
The document header is a special set of contiguous lines at the start of the document that encapsulates the document title, author and revision information, and document-wide attributes (either built-in or user-defined). The header typically begins with a document title
Reference: Titles
The document title resembles a level-0 section title, which is written using a single equal sign = followed by at least one space, then the text of the title. The document title must be the first level-0 section title in the document. The only content permitted above the document title are blank lines, comment lines and document-wide attribute entries.
Reference: Sections
Sections partition the document into a content hierarchy. A section title represents the heading for a section. Section title levels are specified by two to six equal = signs. The number of equal signs in front of the title represents the nesting level (using a 0-based index) of the section.
Section numbering should be in single steps. This means you will get a warning when using = and then ===.
Example:
= Document Title (Level 0)
== Level 1 Section Title
=== Level 2 Section Title
Note: please check for documentation build warnings or use a broken link checker for broken references to anchors!
Each section is by design it's own reference ID called an Anchor which can be referenced with xref in the same or from another document. You can also give the section an own custom ID.
When using Auto-generated IDs some rules apply:
Compared to AsciiDoc's standard, ownCloud has set it's own definition:
- All characters are converted to lowercase
- Spaces, hyphens, and periods are substituted by a dash
-
Example:
xref:my-section[Text to Print]
text
== My Section
text
When using Custom IDs, those replace the auto-generated once. These are very useful when you want to define a stable anchor for linking to a section using a cross reference. The benefit of using custom ID's is, that xref is independent of section text changes which can cause broken links.
Example:
xref:custom_id[Text to Print]
text
[[custom_id]]
== My Section
text
Reference: Defining an Anchor
In the same way creating a custom ID (anchor) for sections, you can create an anchor at any location you want to reference to.
Example:
xref:custom_id[Text to Print]
text
[[custom_id]]
text
Reference: Tables
Tables are delimited by |=== and made up of cells.
Cells are separated by a vertical bar |.
There are many ways to create and format tables, please see the reference for more details.
You can also take a look to already created tables in the documentation.
Example with defining table and cell width size plus the use of headers:
[width="80%",cols="30%,70%",options="header"]
|===
| Header of column 1 | Header of column 2
| Cell in column 1, row 1 | long Cell in column 2, row 1
| Cell in column 1, row 2 | long Cell in column 2, row 2
| Cell in column 1, row 3 | long Cell in column 2, row 3
|===
This example shows that columns can also be written underneath:
[width="90%",cols="20%,80%",options="header",]
|===
| Directory
| Description
| `data/<user>/files_encryption`
| Users’ private keys and all other keys necessary to decrypt the users’ files.
| `data/files_encryption`
| Private keys and all other keys necessary to decrypt the files stored on a system wide external storage.
|===
Reference: Comments
If you want to add a comment in your page to remark a writers note which will not be rendered, use two consecutive slashes //
Example:
// Needs revision as a new release will change the parameter.