Full reference of AsciiDoctor syntax is available here: https://asciidoctor.org/docs/user-manual

Second level header

Reference of selected blocks: https://asciidoctor.org/docs/user-manual/#style

Note.
Warning.
Take attention.
It is important.

This is very important block.

Contains list items:

  • One.

  • Two.

List:

  • Position 1

  • Position 2

Third level header, description list

CPU

Sometimes is needed for PC.

RAM

Is also needed.

Tables

Simple example

Service / Component

Converter Service

Index and Search Service

Sample with joined cells

Key Description

indexer.context.sharepoint.url

Root URL of SharePoint site.
Sample: https://sp.mycompany.i
Sample Cloud: https://mycompany.sharepoint.com

indexer.context.sharepoint.url.preprocess

JS function for modifying URL before every request

Sample: Requesting SP on different port.

indexer.context.sharepoint.request.url.preprocess:
    new Funct({process : function(url) {
      return url.replace("http://sp.mycompany.i", " https://sp.mycompany.i:555");
   }})

indexer.context.sharepoint.user

SharePoint access user.
Sample: myuser
Sample Cloud: myuser@mycompany.com

Code snippets

Extracted "live snippets"

The source link below is automatically extracted to highlighted code snippet during HTML convertion. Attributes from and to allow check actuality of content, remove-leading - deletion of line indent. Here is the snippet of connecting plugins to DocGenerator.

// PzdcDoc snippet of: 'org.pzdcdoc.DocGenerator', lines: 72 - 76

// https://github.com/asciidoctor/asciidoctorj/blob/v2.1.0/docs/integrator-guide.adoc
JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
javaExtensionRegistry.inlineMacro(new JavaDocLink());
javaExtensionRegistry.block(new Snippet());
//javaExtensionRegistry.treeprocessor(new Treeprocessor());

Simple snippets

Configuration or another selected block of code (source adds horisontal scrolling if needed):

# при ошибке правки параметров - обновление таблицы с параметрами, необходимо в случае, если при этом другие параметры изменяются динамическим кодом
onErrorChangeParamsReload=1
# код параметра - категории, который должен быть указан перед переводом процесса в конечный статус
categoryParamId=<param_code>
# требование заполненности параметров перед установкой статуса, одна или несколько записей вида
requireFillParamIdsBeforeStatusSet.<status_to_code>=<param_codes>

Java code:

class My {
   private int a;

   public My() {
                   a = 5;
   }
}

References

Resources

Image, recommended to be places in directory _res near of the file.

image

Big images may be restricted by width, recommended 600px for horizontal oriented и 300 vertical:

image

Any file from a project may be also referenced and automatically copied to _res subdirectory.

Content of class org.pzdcdoc.Snippet

JavaDoc

Link to JavaDoc of the class: ru.bgcrm.dao.user.UserDAO

Cross documents

References to .adoc files being converted to .html links and validated to corectness.

Another document: Module

Chapter in the current document: Snippets

Chapter in another document: About

Use such links for referencing on not ready parts TODO, they may be easily found later.

Such link causes a validation error, may be used for marking not finished places:

<<todo, todo>>

Selections

For any selection except of links use bold font: variable, path, parameter, interface ⇒ menu ⇒ item

Diagrams

Embedded

Supported Ditaa and PlantUML diagrams.

Advantages:

  • lightness;

  • quick preview;

  • simplicity and uniformity;

  • storage and editing in the text of the document;

  • no need to export.

Ditaa

Ditaa is a ASCII-based format of block diagrams. Here is the original page: http://ditaa.sourceforge.net/ and actual repo: https://github.com/stathissideris/ditaa

References:

diag 6f2c72b218b08be31d4d3ddbcaf14845

And a complex sample.

diag 9f248bbe2935cc8b1c94482332759cd7

With 3rd party editors

Schemas can also be produced using third-party editors, for example: yEd Source files are stored in _res directories under names ending in _schema.graphml. Files have to be exported as images in PNG format, preferably with the same name. After any change source files have to be re-exported.

Tools

AsciiDoctor may be edited in any text editor, but as more comfortable way I use an Eclipse plugin.

eclipse plugin

Features:

  • structure preview in Outline section;

  • hot keys like Ctrl + b for typical formatting options.

Preview I normally do not use, just do generation and refresh in the running browser.