Include Processor

Asciidoctor supports including other documents via the include directive. With it, you can simply write include::other.adoc[] to include the contents of the file other.adoc. Include Processors allow to intercept this mechanism and for instance include the content over the network.

For example, similar to the *unix ls command, an Include Processor could resolve the include directive include::ls[], and insert the contents of the current directory in the document. Our example will replace the include directive include::ls[] with the directory contents, adding one line for every file found.


The processor could look like this:
import org.asciidoctor.ast.Document;
import org.asciidoctor.extension.IncludeProcessor;
import org.asciidoctor.extension.PreprocessorReader;

import java.util.Map;

public class LsIncludeProcessor extends IncludeProcessor {    (1)

    public boolean handles(String target) {                   (2)
        return "ls".equals(target);

    public void process(Document document,                    (3)
                        PreprocessorReader reader,
                        String target,
                        Map<String, Object> attributes) {

        StringBuilder sb = new StringBuilder();

        for (File f: new File(".").listFiles()) {

        reader.pushInclude(                                  (4)
                new File(".").getAbsolutePath(),
1 Every Include Processor must extend the class org.asciidoctor.extension.IncludeProcessor.
2 Asciidoctor calls the method handles() with the target for every include directive it finds. The method must return true if it feels responsible for this directive. In our case it returns true if the target is ls.
3 The implementation of the method process() lists the directory contents of the current directory and creates a string with one line per file.
4 Finally the call to the method push_include inserts the contents. The second and third parameters contain the 'file name' of the include content. In our example this will be basically the name ls and the path of the current directory. The parameter 1 is the line number of the first line of the included content. This makes the most sense when partial content is included.