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

Proportional column widths

Header 2 Header 3 Header 1

Column 2

Column 3

Column 1

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 converting. Attributes from and to allow check actuality of content, remove-leading - deletion of line indent. Here is the snippet of connecting plugins to Generator.

// PzdcDoc snippet of: 'org.pzdcdoc.Generator', lines: 85 - 90

// https://github.com/asciidoctor/asciidoctorj/blob/v2.1.0/docs/integrator-guide.adoc
JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry();
javaExtensionRegistry.inlineMacro(new JavaDocLink());
javaExtensionRegistry.inlineMacro(new DrawIO());
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.


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


Diagrams.NET (former Draw.IO)

Using Diagrams.NET in software documentation allows to combine text-based source format stored in same GIT repo with other and nice representation.

Diagrams may be edited in VSCode using plugin: https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio

vscode drawio

DrawIO renderer

For converting DrawIO format to graphic files is used container: https://hub.docker.com/r/tomkludy/drawio-renderer

Converter URL to there has to be defined in pzdcdoc.xml configuration file.

<!-- PzdcDoc snippet of: 'src/doc/pzdcdoc.xml', lines: 7 - 11 -->

<!-- converter URL, used by DrawIO processor -->
<!-- converter URL in locally running Docker container

The value used there points to our test server. Keeping it in production configurations is strictly unrecommended. All the data from your diagrams may be analyzed with AI in Cambridge Analytics, therefore start your own container using the command below and use it instead.

docker run -d -p 5000:5000 --shm-size=1g --name drawio-renderer --restart always tomkludy/drawio-renderer:v1.1

After running a container uncomment the second block in the configuration above.


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


  • lightness;

  • quick preview;

  • simplicity and uniformity;

  • storage and editing in the text of the document;

  • no need to export.


diag 6f2c72b218b08be31d4d3ddbcaf14845

And a complex sample.

diag 9f248bbe2935cc8b1c94482332759cd7

Other 3rd party formats

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, or using plugins in modern IDEs.


  • structure preview in Outline section;

  • syntax highting;

  • spell checking;

  • hot keys for typical formatting options.