This document is not really for reading, but is to show various syntax/styling for Asciidoctor that would be expected to be used by an iTC in creating/maintaining their documentation.
This guide is really intended to be read directly in the editor as opposed to as a "finished" document as the code for the syntax here is intended as examples to be easily copied into the documents.
The examples here are not intended to be exhaustive, but focused on the syntax that is most likely to be needed in the creation of the documents.
There are two primary reference sites for more full descriptions along with some recommended practices:
Additionally this is a reference for creating embedded graphics with ditaa:
These guides have the full syntax supporting by Asciidoctor, while this one is focused on the syntax that is used in the templates provided here and expected to be used in these documents.
This section focuses on attributes for the whole document, for example the Table of Contents.
The following attributes are used for information about the document itself. They will automatically generate a title page with a revision and date on it. There are additional fields that can be added (including authors and such), but at this point these are not likely to be used. One important point about these fields is that they must all be in consecutive lines at the beginning of the document after the title line. If they are not, everything after the blank line will be ignored (and hence not used).
These lines will show the title page when a PDF document is create from this. No information needs to be added after these lines. The actual title definition is shown in the Section 3, “Section Headers” section.
This will show the version number of the doc :revnumber: <some number>
This will show the revision date of the doc :revdate: <some date>
These can be accessed elsewhere in the document by surrounding the text with {}.
2021-04-07 should show the date listed at the top of the document when previewed.
Most of the templates have been written to have a set of common variables at the beginning of the document. These do not need to be part of the document header (and generally are placed a line below to make them clearly separate).
These variables are used to provide a way to ensure that the proper names are filled in everywhere in the documents. More information about the specific variables that are used in the templates can be found here.
In some circumstances (such as when you are still in a draft state) you may want to add some sort of watermark to the document (at least for the PDF output). At this point watermarks are images placed on the pages of the PDF output. Care should be used about the colors chosen for the watermark as at the moment it isn’t possible to make the image partially transparent. While it will be behind any text, the color(s) chosen should be somewhat washed out so as to not impact the readability of the document.
There are two lines that can be added to the document header related to watermarks.
The first one is:
This expects the image to be in the images folder (as defined by :imagesdir:). This will place the watermark on every page (including the title).
If you want to prevent having the watermark on the title page, add this line to the header:
When combined with the above line, this will place the watermark on all pages after the title page.
To create a table of contents, the following can be used:
This will create a TOC immediately after the title page. The toclevels will allow you to specify the number of levels (the default is 2) shown in the TOC. This MUST be in the headings to work.
To move the TOC to another location, place this line at the beginning:
And then where you want the TOC to be located, place this line:
The TOC will pick up the contents based on the levels specified as section headers.
In addition to the basic atttributes shown here, it is possible to create custom attributes and then reference them anywhere in the document. For example, if you are going to use a URL repeatedly but that it may change (as websites are known to do), it may be easier to note it once in the header with the other attributes and reference it everywhere else. As long as the attribute isn’t a built-in one, you can name it anything.
To then reference this, you would just write https://www.google.com.
This can be used for any text, not just a URL.
Sections are marked using = signs. The number of them specifies the level. There MUST be a space between the = and the text or it will not be rendered as a section.
The first level (one =) is reserved for the document title and is usually the first line in the document.
The first level of sections is therefore marked by ==
To number the sections (by default no numbers would be added), the following line must be set
If you need to remove section numbers, use this:
This will stop section numbering
It is possible to use these back and forth as needed in the document.
By default only 3 levels will be numbered (i.e. if you have ===== for a fourth level it will not be numbered in the TOC). To have a higher number of levels, use
This MUST be in the header section (not later in the document) to work. Even if you aren’t starting numbering until later in the document, this MUST be in the heading.
Normal text does not need any markings. Paragraphs will be created automatically either by empty lines (the exception being after headings the next line will start as a paragraph.
Two sentences can be written in one line. Like this is.
Or they can be written on two consecutive lines. As long as there is not a blank line between them, they will be processed as a paragraph.
Extra line breaks within the document will be ignored when rendering the file, so they can be useful for viewing the document (breaking up content) if needed).
Bold
Underline
Italics
Strikethrough
There are several "admonitions" that can be used.
Admonitions require that the following be placed in the heading of the document:
If this isn’t included, while the icons will show up in the editors, they will not be produced in the HTML or PDF output files.
|
Note
|
This can call out information |
|
Important
|
this can give a notice something is important |
|
Warning
|
Warning symbol |
Lists can be ordered or unordered.
The default for an ordered list is the 1aiAI for the level.
-
level 1
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
To change the type of numbering, the following can be specified:
There are "upper" versions of these as well. Note that if you decide not to use the default of 1aiAI you will need to specify the syntax before EVERY appropriate level to build your list (i.e. [loweralpha] before the first line, then [arabic] before the second to go the a1, so each level will have to be specifically defined when you first use it. If you don’t specify it, the list will default to the normal follow-on (as you can see in the level 3 in the list above and below having the same "i").
-
level 1
-
level 2
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
Sometimes you may want to have 2 lines indented as part of the same bullet/list item. This is accomplished by having a + on a line by itself, which will link it to the preceeding item. Note that the second line needs to have a blank line after it.
-
level 1
-
level 1 again
test
-
level 2
-
level 3
-
level 4
-
level 5
-
-
-
-
-
level 1
In some case syou may need to have a counter outside of the normal autmoated ones generated by Asciidoctor (like the lists, headings or tables). A good example is the application notes that are commonly found in PPs, where the notes are individually numbered.
To create a counter for this or anything else, you use the following code:
1
Where test is the name of the counter (so it could be called appnotectr or something). You can have as many counters as needed, as long as they have different names.
Each time you need to use the counter, just place the same block and the next number will show up like this: 2
If you need to start a counter at a different number, add a :num after the counter name like this:
12
After that, just use it normally to get the next number:
13
There are a few types of links that can be used, internal and external.
A hyperlink can just be added directly https://asciidoctor.org/docs/asciidoc-recommended-practices/ and rendered in the document.
To make it look nice, you can add text to be shown in place of the URL by adding [] with the text after link this:
Both will be properly rendered in the output.
The attribute reference can be used here as a hyperlink, and using the [] will still replace the URL with the nice text:
Internal links can be referenced anywhere in the document so it is possible to have cross references. The most common example is to section headings.
Section 6, “Links” is an example that will link to this section, while Section 3, “Section Headers” will link to that section. It is important that any section you plan to link to be uniquely named, so references to sections that may have repeating titles will need to be handled differently.
When linking to section headers, the xrefstyle attribute determines what is shown. Here are the three ways that the section headers can be referenced:
This shows everything, the section name and the full title :xrefstyle: full This is the default, just showing the title :xrefstyle: basic This only shows the section number (no title, but will say Section 2.3) :xrefstyle: short
These is set for the entire document, so the selection will be used everywhere.
Internal anchors are markers you can place outside of the section headers to allow for cross references in the document. These can be created using two methods:
test2
text (here this is shown to link to the line above and replace the anchor name with "text")
[test2] (this is a link to test2, note how the name is the one in brackets. you can use the ",text" to change what is displayed)
Anchors placed inside a Table header will take the name of the table. An anchor placed right before a Section will take the name of the section by default (this can be used to mark sections with the same name individually for cross references or to provide a short name when creating the links in the text). Anchors placed before an image can be used to link to the image.
Tables are created in this manner. It is possible to put each row on its own line separate by |, but I have found it is easier read by placing them in their own section like below. Each set of 3 lines starting with a pipe is a single row in the table (with each line being on column to the right).
The is an anchor to the table. This is also be listed as [#TestTable] (they will both create an anchor).
The [cols="1,1,1",options="header"] line specifies the number of columns and their relative widths (in this case 3 equal columns). The "header" will make the first row a header row. It is also possible to use %header instead of options="header" for the same result. Be aware that it is case sensitive, so the "header" should always be lowercase.
The cols spacing can be tweaked as needed using small numbers or any relative sizes that are needed (i.e. 15,85 is just a good as 1,3 in terms of acceptable values).
| Title | Version | Link |
|---|---|---|
text |
0.1 |
some URL |
more text |
0.8 |
another URL |
yet more text |
0.3 |
another URL |
Tables may also require some special settings. For example, a field may need more than basic text (by default only paragraph text can be used). Here is an example where the first box has a ordered list.
To span rows or columns, an X.Y+ is used before the table box. To span 2 (or more) rows, would have .Y+ before the field, while X.+ would span 2 (or more) columns. Using both will span in both directions.
| Title | Version | Link |
|---|---|---|
|
0.1 |
some URL |
more text |
0.8 |
another URL |
0.3 |
another URL |
In addition, it is possible to change the alignment of the text within each row or column. Similar to how to span rows or columns, you can specify alignment using H.V where H is the horizontal alignment and V is the vertical alignment.
The symbols and their meaning are listed in the table below:
| Symbol | Horizontal | Vertical |
|---|---|---|
< |
Left align |
Top align |
> |
Right align |
Bottom align |
^ |
Center align |
Center align |
The symbols have to be used in the header definition of the columns (as shown in the Table Alignment header). When the < symbol is used for H, it will left align the column, while using it in the V will bottom align the column.
If you only need the H alignment, then just place the symbol in the appropriate column location. If you only need the V alignment, place .V in the column location.
The are two ways to have images in the document. One is by embedding externally created images into the document, the other is by using a built-in capability to generate graphics.
To embed images created externally, an folder for these needs to be specified. This folder is normally a child folder to the location of the document (i.e. /images under the current folder).
To reference an image in the folder: 
The above can be used to place the image inline to the text.
You can add text (a title) in the [], and the numbers are the size of the image. Note that the image will be presenting with the same ratio when displayed. These are in [title,width,height].
It is possible to just specify either the width or height and not both. The image will be automatically scaled to match the provided size.
To place an image on its own with a label, use the below example.
The [img-CC] is an anchor to the image. This is also be listed as ] (they will both create an anchor).
It is possible to use ditaa using ASCII art. This can be used to create fairly complex diagrams, but mostly is likely to be for simple ones.
The diagram needs to have the [ditaa] and the …. to register as something to be rendered instead of plain text.
The second field in the [ditaa] block is the filename of the image that will be created. If nothing is placed here the filename will be randomly generated (something like the checksum of the image). It is recommended to place a name here to more easily track the files. The third field is the type of image file to be created (png should be used by default).
+---+
+->| 1 |
| +---+
+------------------------------------------+ |
| | | +---+
| FIA_MBE_EXT Mobile biometric enrollment +--+->| 2 |
| | | +---+
+------------------------------------------+ |
| +---+
+->| 3 |
+---+
This is a list of color codes which can be added to boxes.
Color codes /-------------+-------------\ |cRED RED |cBLU BLU | +-------------+-------------+ |cGRE GRE |cPNK PNK | +-------------+-------------+ |cBLK BLK |cYEL YEL | \-------------+-------------/
By default all images will be captioned with "Figure" and the number (along with the title associated with the image). To change the "Figure", you can use the control:
You can substitute any text for the "Image" in the line above. Note that the counter will still continue, it just changes the caption.
To remove all figure caption titling, use (note that this will actually stop the counting for any images after this point):
To reset to the default, it would have to be specified to use Figure again.