AsciiDoc is a lightweight markup language, similar to Markdown. We chose AsciiDoc over standard Markdown because it provides more out-of-box capabilities. While it’s more powerful, it’s still simple to use. Refer to this page to get started writing in AsciiDoc.
See the links below for more detail
Headings
= Page title == Level 1 section == Level 2 section ==== Level 3 section ===== Level 4 section |
You can have only one page title, but you can have multiple section titles. For example, you might have three level 1 sections that include level 2 and 3 sections:
= Page title == Level 1 section == Level 2 section == Level 1 section == Level 1 section == Level 2 section ==== Level 3 section |
Bulleted lists
* Item 1 * Item 2 ** Item 2a + Continuation text for the previous list item. * Item 3 |
|
| The + is a list continuation. It keeps the text inline with the list item. Omitting the + affects the formatting of that line. |
Adding another space before the + adopts the indentation of one level higher:
* Item 1 * Item 2 ** Item 2a + Continuation text for the previous list item. * Item 3 |
|
Labeled lists
Item 1:: Description 1 Item 2:: Description 2 |
|
||||
[horizontal] Item 1:: Description 1 Item 2:: Description 2 |
|
When you add [horizontal] above item 1, the label and description appear on the same line. That works well when you have very short descriptions.
Ordered Lists
. number .. loweralpha ... lowerroman . number |
|
We can mix ordered and bulleted lists however we want: * bullet . number ** bullet .. loweralpha |
|
Images
image::file.gif[alt text]
| "alt text" means alternative text. It describes the image that appears on the page. The primary use is for visually-impaired users who use screen readers. |
The image path is obtained by combining the root of the project directory, followed by the imagesdir parameter defined in the preamble, followed by whatever you define in image. So if it is defined as
:imagesdir: images
and we have
image::subdirectory/filename.png[]
Then the full search path is
{projectroot}/images/subdirectory/filename.png
Images with links
You can add a link to an image so it acts like a "button."
Syntax
Use the following syntax when adding your image:
image:<file_name>.<ext>[alt=<text>,link=<url>,window=_blank]
"window=_blank" opens the link in a new browser tab (or window).
For example:
image:logo.png[alt=A button titled ASAM Home,link=https://asam.net,window=_blank] |
|
Links
The syntax that you should use depends on what you’re linking to:
Link to a section on the same page
<<section_title>> e.g. For more details, see <<Headings>>. |
For more details, see Headings. |
The link text can be something other than the section title: <<section_title,Different link text>> e.g. <<Headings,Learn the syntax for headings>> |
You can create custom anchors and link to them as well
I want an anchor [[anchorlabel]] Then I make a <<anchorlabel, link>> to it |
Then I make a link to it |
Notes, tips, etc.
You might want to draw attention to certain statements by creating notes or tips. Format them as follows:
NOTE: text TIP: text IMPORTANT: text CAUTION: text WARNING: text
Use each of these sparingly. You don’t want to create pages that are full of notes and tips. They become less meaningful if you do.
Here’s what each of these looks like when the AsciiDoc content is turned into HTML:
| This is a note. It includes extra info that a reader might need to know. |
| Here’s a tip. A tip provides useful information that can help a user do something or understand something. |
| This is important information that the reader must be aware of so they don’t do something that they shouldn’t. |
| A caution advises the reader to act carefully. Use this in rare circumstances. |
| And this is a warning that informs of danger or harm. This one should be used very rarely, as well. |
If you’re authoring new content, you’ll want to review this section for some nitty-gritty details.
Document headers
Each AsciiDoc file header goes directly underneath the document title (see Headings).
You won’t need to touch any of the parameters in this heading.
Tables
Here’s syntax for a basic table:
[cols=2*,options="header",cols="25,75"] |=== | heading column 1 | heading column 2 | row 1 column 1 | row 1 column 2 | row 2 column 1 | row 2 column 2 |===
There are many ways to format a table. Refer to the AsciiDoctor User Manual for additional help.
Task headings
If you’re explaining how to perform a task, you might include introductory information before you get to the steps. And you might need to say what to do after completing the steps. If you do, it’s best to organize that information using headers, which enables scanning.
Use the following headings as needed:
The information the user needs to complete the task.
Some extra contextual info the user might need to know about this task.
The individual steps to complete the task.
What the user should do next.
Each of these should include a . right before the text, like so:
.What you'll need .About this task .Steps .What's next?
This syntax applies bold text in a larger font.
Code & syntax highlighting
For inline code, enclose it with ` to apply monospace font: `volume show -is-encrypted true` |
For inline code, enclose it with ` to apply monospace font: |
For code blocks: the html in the square brackets tells the compiler that this is html source code for source highlighting. [source, html] ---- <!DOCTYPE html> <html> <body> <h1>My First Heading</h1> <p>My first paragraph.</p> </body> </html> ---- |
|
Content reuse and including files
If you have a chunk of content that’s repeated across different pages, you can easily write it once and reuse it across those pages. Reuse is possible from within the same repository and across repositories. In the files where you’d like to reuse content:
-
If you’re reusing the content from within the same repository, use the following syntax on a line by itself:
include::<filename>.adoc[]
-
If you’re reusing the content in a different repository, use the following syntax on a line by itself:
include::<FILE_RAW_URL>[]
If you want to learn more about the include directive, check out the AsciiDoctor User Manual.