Examples

Here you will find simple but complete examples of how to convert documents using the different configuration options available. The examples cover the main scenarios, but you can mix and match usage of instances, builders and maps freely to suite your needs.

Setting attributes and options as instances

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.

Asciidoctor asciidoctor = Asciidoctor.Factory.create(); (1)

Attributes attributes = Attributes.builder()
                          .backend("docbook")
                          .icons("font")
                          .build(); (2)

Options options = Options.builder()
                    .inPlace(true)
                    .attributes(attributes)
                    .build(); (3)

String outfile = asciidoctor.convertFile(new File("sample.adoc"), options); (4)

1	Create `Asciidoctor` instance.
2	Defines the attributes as an `Attributes` class.
3	Defines the options as an `Options` class.
4	Converts the document passing previously created `Options` instance.

The icons attribute requires a String to set the value used to "draw" icons. At this time, you can use two constants org.asciidoctor.Attributes.IMAGE_ICONS for using the same approach as AsciiDoc, that is using img tags, or org.asciidoctor.Attributes.FONT_ICONS for using icons from Font Awesome.

Setting attributes and options as Map collections

Asciidoctor asciidoctor = Asciidoctor.Factory.create(); (1)

Map<String, Object> attributes = Attributes.builder()
                                   .backend("docbook")
                                   .icons("font")
                                   .asMap();  (2)

Map<String, Object> options = Options.builder()
                                .inPlace(true)
                                .attributes(attributes) (3)
                                .asMap(); (4)

String outfile = asciidoctor.convertFile(new File("sample.adoc"), options); (5)

1	Create `Asciidoctor` instance.
2	Defines attributes using builder fluent API and retrieves them as `Map`.
3	Registers the attributes map as `attributes`.
4	Converts options to `java.util.Map` instance.

Setting attributes and options as builders

Asciidoctor asciidoctor = Asciidoctor.Factory.create(); (1)

AttributesBuilder attributes = Attributes.builder()
                                 .backend("docbook")
                                 .icons("font"); (2)

OptionsBuilder options = Options.builder()
                           .inPlace(true)
                           .attributes(attributes); (3)

String outfile = asciidoctor.convertFile(new File("sample.adoc"), options); (4)

1	Create `Asciidoctor` instance.
2	Defines the attributes as an `AttributesBuilder` by not using `build()`, `get()` or `asMap().
3	Defines the options as an `OptionsBuilder` by not using `build()`, `get()` or `asMap().
4	Converts the document passing `OptionsBuilder` instance.