AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated via the Asciidoctor toolchain to many formats including HTML, PDF, EPUB, DocBook and man page. Any text editor can be used. Some websites, like Github, render AsciiDoc files directly into HTML.

The following listing is an example of a simple Asciidoc file.

You can define the position of the toc.

preamble will position the toc in the main content area (some as default) but before the preable.

If you want to use Asciidoctor directly you have to install its toolchain. If you are using Gradle or Maven as build systems, it is not required to install Asciidoctor separately. Both Gradle or Maven provide plug-ins to execute Asciidoctor tasks.

The title is defined at the top of the .adoc file as

If you want to define a subtitle add a : (a colon followed by a space) after the title

The Author can be written just after the title with or without an attribute.

The author can also include information as an Email or an URL inside angle brackets. It is possible to have a list of authors. Multiple authors and their emails are separated by a semicolon and a space ;.

Without attributes:

With attributes:

Asciidoctor uses the author’s name and email to assign values to built-in attributes that can be used throughout the document’s body. These attributes include: author (firstname and lastname), firstname, lastname, middlename, initials and email.

If there are multiple authors you can refere to them by using the following convention: {firstname2}, {firstname3}, etc.

The revision information is listed on the third line of the .adoc document, beneath the author information line with or without attributes. It can include the following data:

Revision number and revision date are separated by a , (comma and space). Revison Remark is separated by a : (colon and space).

Without attributes:

With attributes:

Use the following to highlight your text.

The result looks like the following:

This is bold text

This is cursiv text

This is mono text

A + (plus) at the end of a line with a following space forces a line break.

++SPACE

Asciidoc determines automatically links in the content of your document, if the link starts with http:// or https://. You can also define a anchor text via [] directly after the link.

The result looks like the following.

vogella

https://www.vogella.com

In order to include a link with white spaces or special characters as for example

the definition should look like this:

You can import files via the include macro. This also works for source code includes. To use ---- in your listing use the [listing] style before that. The following example imports a file formatted as Java source code.

Result:

Via the leveloffset attribute you can change the section offset, for example a = section will become == if you add the following statement:

Use the following statement to reset the offset.

It is also possible to include files partially. For this mark the part of the file to be included with a tag like the following:

and include the file with the tagname in the brackets like this:

The result would be

You can import images with image:: for the HTML output you can add the alt text within the brackets []. If the image is located in the img folder then the import would look like this:

The import of an image with image:: will add the image in a new line. If you want to add an image inline then use the macro: image:

Result:

This is just a text to show inline images.

It is possible to include or exclude text based on document attributes or based on the value of a document attribute. The attributes ifdef, ifndef and ifeval can be used to achieve this.

To include content, if the attribute exercise_solution is set use the following syntax:

To include content if the attribute exercise_solution is not set, use the following syntax:

It is also possible to use multiple attributes. If the attribute names are separated by a , (comma) only one of the attributes need to be set to include the content. If they are separated by a + (plus) all attributes must be set to include the content.

With the ifeval attribute it is possible to evaluate the value of attributes. If the expression is true then the content is included in the document, otherwise it is not.

In this case the text This is a good one! will be shown.

Lists can be defined with the * operator at the beginning of a line. You can define up to 6 levels for a list. Ensure to have a space before the list element. Example:

Result:

Numbered lists start with the .

Result:

Additional paragraphs, blocks, images, source code, etc. are adjoined to a list element by putting a plus sign (+) on a line adjacent to both blocks.

Result:

You can define menus and buttons. This requires the activation of an experimental feature, via the ** attribute in the header section of your document.

The result looks like the following.

View  Zoom  Reset.

Press the OK button when you are finished.

You can also define keyboard shortcuts with the kbd macro.

The result is the following:

Alt+F11 - Toggle Full Screen Mode in the Eclipse IDE

To reference images in your AsciiDoc with the image:: macro pointing to a relative file location. Use brackets to define a fixed or related size.

The result looks like the following:

You can also define a text for the image which is for example used for screenreaders or as placeholder if the image cannot be found.

If you want to scale the image for the PDF output you can use the pdfwidth attribute.

You can also add the ` font` directive to the top of your document, which allows you to use the icons from http://fortawesome.github.io/Font-Awesome/icons/ directory via a marco.

The output looks like the following

This is a comment icon

And a file icon

And a battery icon

If you would like to use a specific set of icons use the following definition

To define a link use

You can link to titles that have auto-generated ids, but the formation of the ids could vary based on the attributes idprefix and (for Asciidoctor) idseparator. The default is to make the title text lowercase, prefix with an underscore, and replace spaces and other punctuation with underscores. The id for the title "Let’s make a game!" would be _lets_make_a_game.

It is often better for you to specify your own id that will remain stable even if you edit the text of a title. You can do so with:

where id is the identifier you want to specify, and label is the optional, default label that may be used for the cross reference (if the cross reference itself doesn’t specify a caption).

The markup for an internal cross reference is:

You can assign meta data to a block. Here’s an example of a quote block that includes all types of metadata:

You can create also tables in Asciidoc via the following syntax.

The result looks like the following.

You can also define the relative table width.

Of course you can define tables with more than two columns.

To show part of the text as source code use the following:

Use monospace text formatting to emulate how source code appears in computer terminals, simple text editors, and integrated development environments (IDEs). Enclose the starting hypthen string with \ for this, e.g., `System.out.println("Hello");` results in System.out.println("Hello");

To enable syntax highlighting in the output, set the style on the block to source and specify the source language in the second attribute position. The possible highlighting styles are described in chapter Source code highlighting.

The supported languages depends on your renderer but your can for example use:

If you need to escape Asciidoc commands, you can use \ before the character that would normally be interpreted by Asciidoc. To write for example | you would need to write it like this: \|.

You can add primary index terms to your document via (((yourterm))). A secondary index can be added to your document via (((yourterm, secondary term2))). For example:

((((Big cats)))

((((Big cats, Lions)))

You can add comments to the Asciidoc markup. The comments are not added to the generated output. You can use both single and multiline comments. Single line comments start with a double slash (//). Multiline comments are enclosed in a block of four forward slashes (////).

Most AsciiDoc elements can be escaped by preceding them with a backslash character.

You can define custom variables and use them in your document. For example the following defines the variable yourvariable which can be used with {yourvariable} and Asciidoctor will replace it with the value defined after the second :.

AsciiDoc supports the native <details> element to hide elements and make them available on click.

To convert your asciidoc files you need to install the Asciidoctor gem.

If you want to be able to create pdf-files you can use the asciidoctor-pdf gem.

Because Asciidoctor will default to the html5 backend you don’t need to call it with any extra arguments.

To see a list of all available backends you can call asciidoctor --help.

After the installation of the gems you are ready to convert your AsciiDoc files to pdf-format.

If you want to use the latest development version of asciidoctor to create your pdf-files you have to clone the asciidoctor-pdf repository from Github.

To get the application ready you first need to install the dependencies. You might have to install the bundler gem first.

Now you can start using the latest version to convert your AsciiDoc.

An admonition paragraph draws the reader’s attention to certain information. It can be defined by a predefined label at the beginning of the paragraph or as a block.

The result looks like the following:

Here are the other built-in admonition types:

You can also use admonition blocks.

The output looks like the following.

Similar to a tip, you can add a warning.

The output looks like the following.

The following styles are supported:

You can also add header to these admonitions.

This looks like the following:

will look like this:

The title page of a pdf document can include the following attributes:

This attributes can be styled in the file basic-theme.yml in folder themes.

To see the links in the generated output use the following attribute in the header of you document.

Also you can configure the label for a chapter via the chapter-label attribute, e.g. if you do not want any label you can use:

Unfortunately Asciidoctor does not add a page break before a part if you use "book" as output. See https://github.com/asciidoctor/asciidoctor-pdf/issues/329. As workaround you have to put manual line breaks into it with <<<.

You can add an index to your pdf output by defining it as follows:

This will list all the defined indexes. The output will look like this:

The appendix is defined as follows:

In order to style the PDF output use the file basic-theme.yml in folder themes. In this file you can style the title page, the headings (h1, h2, h3, etc), the images and many more objects.

For example to style the heading do the following entry in the basic-theme.yml file:

A useful feature is to set a default width for images in the pdf output. To achieve this do the following entry:

To see all possible styling settings visit the Asciidoc theming guide.

In order to use some publishing attributes you must set the media attribute in the header of your AsciiDoc document as follows:

This attribute will trigger the following settings:

Use the sectlinks attribute to turn titles into links. Use the sectanchors attribute to add anchor before the section title, by default § is used.

See https://docs.asciidoctor.org/asciidoc/latest/sections/title-links/#anchor for details.

The default styling of the asciidoctor tooling is good for most cases. But some cases require the use of custom templates to modify the output for the use case.

This requires to specify the option template_dir in the config file.

For gradle:

For Asciidoctor CLI tooling use the -T parameter:

$ asciidoctor <target_file> -T '<template_folder>'

Templates can be written in haml or slim. You can find example templates written by the asciidoctor project at https://github.com/asciidoctor/asciidoctor-backends.

You can add content to the header of the HTML output. See http://asciidoctor.org/docs/user-manual/#docinfo-file for details.

If you need more assistance we offer Online Training and Onsite training as well as consulting

See License for license information.