WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header.
NOTE: The number of equal signs matches the heading level in the HTML output.
For example, _Section Level 1_ becomes an `<h2>` heading.
.Book doctype
----
include::{includedir}/ex-section.adoc[tag=book]
----
[.result]
====
include::{includedir}/ex-section.adoc[tag=b-book]
====
////
IMPORTANT: There are two other ways to define a section title.
_Their omission is intentional_.
They both require more markup and are therefore unnecessary.
The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone.
The reader never sees the extra markup, so why type it?
*Be frugal!*
////
.Explicit id
----
[#primitives-nulls]
== Primitive types and null values
----
.Section anchors and links (Asciidoctor only)
`sectanchors`::
When this document attribute is set, a section icon anchor appears in front of the section title.
`sectlinks`::
When this document attribute is set, the section titles become self-links.
This enables a reader to bookmark the section.
NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly.
== Include Files
.Document parts
----
include::{includedir}/ex-include.adoc[tag=base]
----
CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated.
Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed.
.Include content from a URI
----
include::{includedir}/ex-include.adoc[tag=uri]
----
NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater.
Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI.
== Breaks
.Hard line break
----
include::{includedir}/ex-text.adoc[tag=hb-all]
----
[.result]
====
include::{includedir}/ex-text.adoc[tag=hb-all]
====
.Thematic break (aka horizontal rule)
----
include::{includedir}/ex-hr.adoc[tag=in-between]
----
[.result]
====
include::{includedir}/ex-hr.adoc[tag=in-between]
====
.Page break
----
<<<
----
== Lists
.Unordered, basic
----
include::{includedir}/ex-ulist.adoc[tag=base]
----
[.result]
====
include::{includedir}/ex-ulist.adoc[tag=base]
====
.Unordered, basic (alt)
----
include::{includedir}/ex-ulist.adoc[tag=base-alt]
----
[.result]
====
include::{includedir}/ex-ulist.adoc[tag=base-alt]
====
NOTE: A blank line is required before and after a list to separated it from other blocks.
TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list.
The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider.
.Unordered, max nesting
----
include::{includedir}/ex-ulist.adoc[tag=max]
----
[.result]
====
include::{includedir}/ex-ulist.adoc[tag=max]
====
TIP: The unordered list marker can be changed using {uri-marker}[block styles].
.Ordered, basic
----
include::{includedir}/ex-o-list.adoc[tag=b-base]
----
[.result]
====
include::{includedir}/ex-o-list.adoc[tag=b-base]
====
NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence.
.Ordered, nested
----
include::{includedir}/ex-o-list.adoc[tag=nest]
----
[.result]
====
include::{includedir}/ex-o-list.adoc[tag=nest]
====
.Ordered, max nesting
----
include::{includedir}/ex-o-list.adoc[tag=max]
----
[.result]
====
include::{includedir}/ex-o-list.adoc[tag=max]
====
TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`.
.Checklist
----
include::{includedir}/ex-ulist.adoc[tag=check]
----
[.result]
====
include::{includedir}/ex-ulist.adoc[tag=check]
====
TIP: Checklists can use {uri-checklist}[font-based icons and be interactive].
Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default.
You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro.
The `imagesdir` attribute can be an absolute path, relative path, or base URL.
When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended.
.Block
----
include::{includedir}/ex-image.adoc[tag=base]
include::{includedir}/ex-image.adoc[tag=alt]
include::{includedir}/ex-image.adoc[tag=attr]
include::{includedir}/ex-image.adoc[tag=ab-url]
----
[.result]
====
include::{includedir}/ex-image.adoc[tag=base]
include::{includedir}/ex-image.adoc[tag=alt]
include::{includedir}/ex-image.adoc[tag=attr]
include::{includedir}/ex-image.adoc[tag=ab-url]
====
.Inline
----
include::{includedir}/ex-image.adoc[tag=in]
----
[.result]
====
include::{includedir}/ex-image.adoc[tag=in]
====
IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image.
(All macros follow this pattern).
You use an inline image when you need to place the image in a line of text.
Otherwise, you should prefer the block form.
.Inline image with positioning role
----
include::{includedir}/ex-image.adoc[tag=in-role]
----
[.result]
====
include::{includedir}/ex-image.adoc[tag=in-role]
====
TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images].
.Embedded
----
include::{includedir}/ex-image.adoc[tag=data]
----
NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs].
TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`.
== Videos
.Block
----
include::{includedir}/ex-video.adoc[tag=base]
include::{includedir}/ex-video.adoc[tag=attr]
----
.Embedded Youtube video
----
include::{includedir}/ex-video.adoc[tag=you]
----
.Embedded Vimeo video
----
include::{includedir}/ex-video.adoc[tag=vim]
----
TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro.
.Code block sourced from file relative to source directory
....
include::{includedir}/ex-src.adoc[tag=rel]
....
[listing]
.Strip leading indentation from source
....
include::{includedir}/ex-src.adoc[tag=ind]
....
[NOTE]
====
* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces).
* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value.
====
.Code block without delimiters (no blank lines)
----
include::{includedir}/ex-src.adoc[tag=src-para]
----
[.result]
====
include::{includedir}/ex-src.adoc[tag=src-para]
====
[IMPORTANT]
.Enabling the syntax highlighter
====
Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument.
:source-highlighter: pygments
The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`.
====
== More Delimited Blocks
.Sidebar
----
include::{includedir}/ex-sidebar.adoc[tag=base]
----
[.result]
====
include::{includedir}/ex-sidebar.adoc[tag=base]
====
NOTE: Any block can have a title, positioned above the block.
A block title is a line of text that starts with a dot.
The dot cannot be followed by a space.
.Example
----
include::{includedir}/ex-example.adoc[tag=base]
----
[example.result]
--
include::{includedir}/ex-example.adoc[tag=base]
--
[#admon-bl]
.Admonition
----
include::{includedir}/ex-admon.adoc[tag=b-bl]
----
[.result]
=====
include::{includedir}/ex-admon.adoc[tag=b-bl]
=====
[TIP]
.Admonition and callout icons
====
Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS.
To use this feature, set the value of the `icons` document attribute to `font`.
Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block.
Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled].
<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters.
<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header.
.Table with two columns, a header, and two rows of content
<1> The `+*+` in the `cols` attribute is the repeat operator.
It means repeat the column specification across the remaining of columns.
In this case, we are repeating the default formatting across 2 columns.
When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header.
.Table with three columns, a header, and two rows of content
.Attribute assignment precedence (highest to lowest)
- Attribute passed to the API or CLI that does not end in `@`
- Attribute defined in the document
- Attribute passed to the API or CLI that ends in `@`
- Intrinsic attribute value (default values)
TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value.
// Table of predefined attributes for character replacements
docker run --rm -v $(pwd):/documents/ registry.vlabs.uniwa.gr:5080/swarmlab-asciidoctor asciidoctor --safe -b html5 -a theme=flask -a toc2 -a toc-placement=right -o ./path/to/FILENAME.html ./path/from/FILENAME.adoc
