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.

Complex admonition blocks: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#admon-bl

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

Proportional column widths

Header 2 Header 3 Header 1

Column 2

Column 3

Column 1

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 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: 112 - 117

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

# при ошибке правки параметров - обновление таблицы с параметрами, необходимо в случае, если при этом другие параметры изменяются динамическим кодом
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.processor.snippet.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 and file names use bold font: variable, path, parameter, interface / menu / item

Diagrams

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 -->
<pzdc-drawio-converter>https://drawio.bgerp.org/convert</pzdc-drawio-converter>
<!-- converter URL in locally running Docker container
<pzdc-drawio-converter>http://127.0.0.1:5000/convert</pzdc-drawio-converter>
-->

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

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

Advantages:

  • lightness;

  • quick preview;

  • simplicity and uniformity;

  • storage and editing in the text of the document;

  • no need to export.

References:

diag 6f2c72b218b08be31d4d3ddbcaf14845

And a complex sample.

diag 9f248bbe2935cc8b1c94482332759cd7

PlantUML

PlantUML diagrams are also supported.

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.

Tools

AsciiDoctor may be edited in any text editor, or using plugins in modern IDEs.

Features:

  • structure preview in Outline section;

  • syntax highting;

  • spell checking;

  • hot keys for typical formatting options.

VSCode Plugin

vscode plugin

Eclipse Plugin

eclipse plugin