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)
                        .headerFooter(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.

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(
        IOUtils.toString(new FileReader(targetFile)),
        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.

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 JavaScripts

  • 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

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);

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"));

attributes

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

  1. 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();
  2. 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");
  3. 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);