AsciidoctorJ's "convertFile(s)" methods don't return html

Hi there, I'm trying out AsciidoctorJ and the sample code from the readme doesn't work as described. It doesn't return an html string but instead creates an html file in the same directory as the Asciidoc file to convert:

From the readme file:

String html = asciidoctor.convertFile(
    new File("sample.adoc"),
    new HashMap<String, Object>());
System.out.println(html);

This code will create a file named sample.html in the same directory. How can I get the convertFile(s) methods to return an html string? It should be noted the convert("blah blah") method does work as expected and returns an html string. Should I file an issue?

Thanks,
Sean

Hi Sean,

First of all, I have to admit that the documentation (and API interface) in the README can be confusing and should be clearer, please feel free to open and issue or propose any recomendation on the repo :).
The thing is that the String is only returned when the output is not rendered to a File, and by default the output is written to a file in the same folder. If you want to render the documents "on-the-fly" you have two options:

1. Enable the option not to render to a file with the "setFile(false)" option:

        Asciidoctor instance = Asciidoctor.Factory.create();

        File input = new File("src/asciidoc/sample.adoc");
        OptionsBuilder options = OptionsBuilder.options().toFile(false); *
        String output = instance.convertFile(input, options.asMap());

        Assert.assertNotNull(output);

2. Use the "convert" method with a reader and a writter:

        Asciidoctor instance = Asciidoctor.Factory.create();

        FileReader fr = new FileReader(new File("src/asciidoc/sample-2.adoc"));
        StringWriter sw = new StringWriter();      
        // This convert method returns void
        instance.convert(fr, sw, OptionsBuilder.options().asMap()); *

        Assert.assertNotNull(output);

(*) Note the use of OptionBuilder to create the options map, I recomend it since it makes everything easier and reduces the chances of typos in the parameters.

For the sake of completeness, there's a third option; transforming the input file to a String and converting it, but this is not a good option since you may encounter encoding and memory issues.

Thank you for your quick reply and help, that works great. I must have missed the toFile option. I'll try and propose an update to the docs to make it a bit more straightforward.

Another question that has more to do with the Asciidoctor processor and less AsciidoctorJ -- There are topic attributes I want to enable globally but not declare in each file, for example the sectanchors attribute. Is it possible to pass these as an option/attribute to the processor and apply them at conversion?

Thanks,
Sean

Seems you're lucky so far, you can indeed pass attributes to the Asciidoctor instance and they will apply to all documents. There's a helper class called AttributesBuilder that provides a front-end for the more common cases, here is an example:

       
        AttributesBuilder attributes = AttributesBuilder.attributes();
        attributes.setAnchors(true);

        OptionsBuilder options = OptionsBuilder.options().toFile(false);
        options.attributes(attributes.get());

Note that some attributes require some special treatment because Asciidoctor (I mean the ruby backend) deals with some attributes in a special way (e.g. linkcss). Anyway, using the Builder you should be fine.

If you have any trouble with those special cases, you can have a look at this section https://github.com/asciidoctor/asciidoctorj#conversion-options, and check the main class of the maven plugin (https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/src/main/java/org/asciidoctor/maven/AsciidoctorMojo.java).
In AsciidoctorMojo you will find examples of how to set options, attributes, how to deal with paths, and other issues you may encounter using AsciidoctorJ.

I hope this helps, if you have any other question just ask.

Once again, very helpful, thank you. If I have more questions I'll ask.