Advanced topics

Add attributes to blocs

Element attributes are a powerful means of controlling the built-in settings of individual block and inline elements in the AsciiDoc syntax.

— Asciidoctor documentation website

Some attributes can be set to blocs directly from the Create functions. For example, you can set the alignment of a paragraph during its creation. But if some predefined attributes exist, the user-defined attributes cannot be known by the toolkit.

To set attributes to any of the blocs that can support them use the property node below.

Figure 1. Center a table using a bloc attribute

Render adoc file using a custom installation of the Asciidoctor toolchain

Rendering toolchain general information

To generate a PDF/HTML file from adoc files, Asciidoctor is needed, which is written in Ruby.

If your adoc file contains diagrams, you need a way to transform the diagram text syntax into an image. Currently, Asciidoctor supports two extensions:

asciidoctor-diagram

asciidoctor-diagram is the default way to transform text descriptions into an image. The issue is that this extension needs the rendering tools associated with the diagram syntax you use in your adoc. Handling all the syntaxes can be tricky.

One rendering tool is graphviz, which depends on Java.

asciidoctor-kroki

Kroki provides an HTTP API to convert plain text diagrams to images and supports lots of diagrams. By default, the public kroki server is used, so be aware, that online access is needed and that you might be sharing confidential information. To overcome these disadvantages, you can use a local Kroki server.

To provide the rendering feature as an "out-of-the-box" experience, AsciiDoc toolkit for LabVIEW™ installs a custom ruby runtime and the Ruby gems needed to convert adoc files to PDF or HTML files.

Images are generated through the public Kroki.io server.

The code below will use the Asciidoctor toolchain installed by the toolkit.

Figure 2. Default rendering code

There are plenty of reasons to use another Asciidoctor toolchain to render your adoc files. We try to provide a way to help you use those custom installations.

to install the Asciidoctor toolchain locally, you can refer see this document

In the following sections, we list the main use cases you may come across to make you use a different toolchain.

Use a local Kroki server

For security reasons or performance issues, you may want to use a self-managed Kroki server instance to generate the picture of the diagrams contained in the adoc files.

To use this instance, specify its URL in the Init function.

Figure 3. Custom Kroki server

Use ascidoctor-diagram instead of Kroki

You don’t want to use Kroki to generate the picture of the diagrams contained in the adoc files. In this case, you need to specify the method in the Init function. You may also probably need to specify the path of the Asciidoctor instance you use.

Figure 4. Asciidoctor-diagram method

using the Ascidoctor Diagram extensions will invoke the necessary external diagram rendering tools to produce an image file that is inserted into your converted document. This implies you will have to install all the these tools on your own.

Set options to the rendering command

There are many options available to run the Asciidoctor toolchain command line. They can be useful for debugging and also to set document attributes during the conversion process without modifying the adoc files. To set those options use the property node below.

Figure 5. Set options

Manual Toolchain Install on Linux

Manual installation is suitable for avoiding the installer dialogues if you want to do the process silently e.g. as part of CI/CD or via a CLI.

Ubuntu and other distros with `apt`

In a future release there will be the option to automate the installation of the Ruby gems if you make a sudoers file - dialogues in the installer will guide you through doing this. If you would prefer to install manually, execute the following commands then install the VI package:

sudo apt update
sudo apt install ruby-full -y
sudo gem install asciidoctor
sudo gem install asciidoctor-pdf
sudo gem install asciidoctor-kroki
sudo gem install asciimath

Distros without `apt`

The installation of the ruby gems has not yet been automated for these. Before installing the VI package, please run:

OpenSUSE/other distro with zypper

sudo zypper refresh
sudo zypper install -y ruby
sudo gem install asciidoctor
sudo gem install asciidoctor-pdf
sudo gem install asciidoctor-kroki
sudo gem install asciimath

Red Hat or distro with dnf

sudo dnf install -y ruby
sudo gem install asciidoctor
sudo gem install asciidoctor-pdf
sudo gem install asciidoctor-kroki
sudo gem install asciimath

Checking installation

You can check the installation with:

asciidoctor --version
asciidoctor-pdf --version
gem which asciidoctor-kroki
gem which asciimath

Render adoc files on Mac

The installation of the Asciidoctor toolchain is not currently supported on Linux and Mac operating systems. You have to install the toolchain manually.

Therefore, the fonctions related to the toolchain are not working on this OS.

However,you can get the command line to generate the PDF or HTML file with the Obtain Command Line function and call it with the appropriate operating system function.

Figure 6. Obtain the command line to convert your adoc file