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.

Render adoc files on Linux or Mac

The installation of the Asciidoctor toolchain is not currently supported on Linux and Mac operating systems. However, if you have installed the toolchain manually, you can get the command line to generate the PDF or HTML file with the Obtain Command Line function.

You will need to call this command with the appropriate operating system function.

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

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 6. Set options