Conversion Options

Asciidoctor provides many options that can be passed when converting content. This section explains the most important and commonly used options when converting Asciidoctor content.

The options for conversion of a document are held in an instance of the class org.asciidoctor.Options. The builder OptionsBuilder (obtained via Options.builder()) allows for simple configuration of that instance that can be passed to the respective methods of the Asciidoctor interface. The following example shows how to set the options so that the resulting HTML document is rendered for embedding it into another document. That means that the result only contains the content of a HTML body element:

Example for converting to an embeddable document

String result =
        asciidoctor.convert(
                "Hello World",
                Options.builder()            (1)
                        .standalone(false)   (2)
                        .build());           (3)

assertThat(result, startsWith("<div "));

1	Create a new `OptionsBuilder` that is used to prepare the options with a fluent API.
2	Set the option `header_footer` to `false`, meaning that an embeddable document will be rendered,
3	Get the built `Options` instance and pass it to the conversion method.

The convert method is overloaded so org.asciidoctor.Options, org.asciidoctor.OptionsBuild or java.util.Map can be used.

attributes

This option allows to define document attributes externally. There are several ways to accomplish that.

Use Attributes.builder() to obtain a fluent API builder.

This is the supported method for its ease of use and type validation. Other way found below have been deprecated since v2.4.4 and may not be available in future releases.

Attributes builder initialization

Attributes attributes = Attributes.builder()
                            .icons("font")
                            .experimental(true)
                            .attribute("my-attribute", "my-value")
                            .build();

The builder also allows passing a chain of values in a String or Array.

Attributes builder initialization as String

Attributes attributes = Attributes.builder().arguments("toc numbered").build();

Attributes builder initialization as String array

String[] attributesArray = new String[]{"toc", "source-highlighter=coderay"};
Attributes attributes = Attributes.builder().arguments(attributesArray).build();

Create an instance of Attributes and set them as a normal POJO.
Attributes instance initialization as POJO
```
Attributes attributes = new Attributes();
attributes.setBackend("pdf");
attributes.setExperimental(true)
attributes.setAttribute("my-attribute", "my-value");
```
It is also possible to use a String of attributes similar to the CLI.
Attributes instance initialization as String
```
attributes.setAttributes("toc numbered icons=font");
```

Directly pass a collection of key-values using Map<String,Object>.

Attributes instance initialization as Map

Map<String, Object> attributesMap = new HashMap<>();
attributesMap.put("icons", "font");
attributesMap.put("experimental", Boolean.TRUE);
attributesMap.put("my-attribute", "my-value");

Attributes attributes = new Attributes(attributesMap);

Attributes builder initialization as Map

Map<String, Object> attributesMap = new HashMap<>();
attributesMap.put("icons", "font");
attributesMap.put("experimental", Boolean.TRUE);
attributesMap.put("my-attribute", "my-value");

Attributes.builder()
            .attributes(attributesMap);

backend

Defines the target format for which the document should be converted. Among the possible values are html5, pdf or docbook.

Converting a document to PDF

File targetFile = // ...
asciidoctor.convert(
        "Hello World",
        Options.builder()
                .backend("pdf")
                .toFile(targetFile)
                .safe(SafeMode.UNSAFE)
                .build());

assertThat(targetFile.length(), greaterThan(0L));

inPlace

Tells the converter to store the output to a file adjacent to the input file. This is true by default.

Setting inPlace option

OptionsBuilder optionsBuilder =
            Options.builder().inPlace(true);

safe

Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. Each level includes the restrictions enabled in the prior security level. All safe modes are defined by the enum org.asciidoctor.SafeMode.

The safe modes in order from most insecure to most secure are:

UNSAFE

A safe mode level that disables any security features enforced by Asciidoctor.

This is the default safe mode for the CLI.

SAFE

This safe mode level prevents access to files which reside outside of the parent directory of the source file. It disables all macros, except the include directive. The paths to include files must be within the parent directory. It allows assets to be embedded in the document.

SERVER

A safe mode level that disallows the document from setting attributes that would affect the rendering of the document. This level trims the attribute docfile to its relative path and prevents the document from:

setting source-highlighter, doctype, docinfo and backend
seeing docdir

It allows icons and linkcss.

SECURE

A safe mode level that disallows the document from attempting to read files from the file system and including their contents into the document. Additionally, it:

disables icons
disables the include directive
data can not be retrieved from URIs
prevents access to stylesheets and JavaScript files
sets the backend to html5
disables docinfo files
disables data-uri
disables docdir and docfile
disables source highlighting

Asciidoctor extensions may still embed content into the document depending on whether they honor the safe mode setting.

This is the default safe mode for the API.

So if you want to render documents in the same way as the CLI does you have to set the safe mode to Unsafe. Without it you will for example not get the stylesheet embedded into the resulting document.

Converting a document in unsafe mode

File sourceFile =
    new File("includingcontent.adoc");
String result = asciidoctor.convertFile(
        sourceFile,
        Options.builder()
                .safe(SafeMode.UNSAFE) (1)
                .toFile(false)         (2)
                .build());

assertThat(result, containsString("This is included content"));

1	Sets the safe mode from `SECURE` to `UNSAFE`.
2	Don’t convert the file to another file but to a string so that we can easier verify the contents.

The example above will succeed with these two asciidoc files:

includingcontent.adoc

= Including content

include::includedcontent.adoc[]

includedcontent.adoc

This is included content

sourcemap

Keeps track of the file and line number for each parsed block. This is useful for tooling applications where the association between the converted output and the source file is important. The default for this option is false.

Setting the option sourcemap

OptionsBuilder optionsBuilder =
            Options.builder().sourcemap(true);

standalone

If true, generates a standalone output document (which includes the shell around the body content, such as the header and footer). When converting to a file, the default value is true. Otherwise, the default value is false.

Setting the option sourcemap

OptionsBuilder optionsBuilder =
            Options.builder().standalone(false);

This option replaces and works in the same way as the previous headerFooter.

templateDirs

Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates.

Setting templateDirs option

OptionsBuilder optionsBuilder =
            Options.builder().templateDirs(new File("templates_path"));

toFile

Via the option toFile it is possible to define if a document should be written to a file at all and to which file.

To make the API return the converted document and not write to a file set toFile(false).

To make Asciidoctor write to the default file set toFile(true). The default file is computed by taking the base name of the input file and adding the default suffix for the target format like .html or .pdf. That is for the input file test.adoc the resulting file would be in the same directory with the name test.html.
This is also the way the CLI behaves.

To write to a certain file set toFile(targetFile). This is also necessary if you want to convert string content to files.

The following example shows how to convert content to a dedicated file:

Example for converting to a dedicated file

File targetFile = //...
asciidoctor.convert(
        "Hello World",
        Options.builder()
                .toFile(targetFile)    (1)
                .safe(SafeMode.UNSAFE) (2)
                .build());

assertTrue(targetFile.exists());
assertThat(
        Files.readString(targetFile.toPath()),
        containsString("<p>Hello World"));

1	Set the option `toFile` so that the result will be written to the file pointed to by `targetFile`.
2	Set the safe mode to `UNSAFE` so that files can be written. See safe for a description of this option.