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

Take attention.
It is important.

This is very important block.

Contains list items:

  • One.

  • Two.


  • Position 1

  • Position 2

Third level header, description list


Sometimes is needed for PC.


Is also needed.


Simple example

Service / Component

Converter Service

Index and Search Service

Sample with joined cells

Key Description


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


JS function for modifying URL before every request

Sample: Requesting SP on different port.

    new Funct({process : function(url) {
      return url.replace("http://sp.mycompany.i", " https://sp.mycompany.i:555");


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):

# при ошибке правки параметров - обновление таблицы с параметрами, необходимо в случае, если при этом другие параметры изменяются динамическим кодом
# код параметра - категории, который должен быть указан перед переводом процесса в конечный статус
# требование заполненности параметров перед установкой статуса, одна или несколько записей вида

Java code:

class My {
   private int a;

   public My() {
                   a = 5;



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


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


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

Content of class org.pzdcdoc.Snippet


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>>


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



Supported Ditaa and PlantUML diagrams.


  • lightness;

  • quick preview;

  • simplicity and uniformity;

  • storage and editing in the text of the document;

  • no need to export.


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


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.


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

eclipse plugin


  • 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.