AsciidocFormatter provides high level methods to generate asciidoc text.

Each section of this documentation explain one method of the AsciidocFormatter. For each method, we describe:

  • how it can be uses in code

  • what the asciidoc generated will look like at the end (except when it’s not possible)

  • the asciidoc text generated

Standard options

Standard option to add at the begining of the document. (Description from asciidoctor Documentation)

  • sourcedir: Path to locate source files.

  • source-highlighter: Source code highlighter to use.

  • docinfo:

Usage

output = formatter.standardOptions();

Asciidoc generated

:sourcedir: ..
:source-highlighter: rouge
:docinfo:

Table of content

Usage

output = formatter.tableOfContent(3);

Asciidoc generated

:toc: left
:toclevels: 3,

Title

Usage

output = formatter.title(2, "Description");

Asciidoc generated

== Description

Paragraph

Each text is written in a separate line on asciidoc file. There is no line break when text is rendered in HTML.

Usage

output = formatter.paragraph("We write some sentences.",
        "Each of them are in is own line in asciidoc text.",
        "They are in a same paragraph at the end.");

Render

We write some sentences. Each of them are in is own line in asciidoc text. They are in a same paragraph at the end.

Asciidoc generated

We write some sentences.
Each of them are in is own line in asciidoc text.
They are in a same paragraph at the end.

Suite of paragraphs

Join paragraph with enough line break to separate them.

Usage

output = formatter.paragraphSuite("My first paragraph.",
        "The second paragraph with a blank line before to separate from the first one.");

Render

My first paragraph.

The second paragraph with a blank line before to separate from the first one.

Asciidoc generated

My first paragraph.

The second paragraph with a blank line before to separate from the first one.

Style

Bold

Usage

output = formatter.bold("bold text");

Render

bold text

Asciidoc generated

*bold text*

Italic

Usage

output = formatter.italic("italic text");

Render

italic text

Asciidoc generated

_italic text_

Description

Usage

output = formatter.description("Describe something.");

Render

Describe something.

Asciidoc generated

Describe something.

Definition

Usage

output = formatter.addDefinition("Asciidoctor", "A fast text processor & publishing toolchain for converting AsciiDoc to HTML");

Render

Asciidoctor

A fast text processor & publishing toolchain for converting AsciiDoc to HTML

Asciidoc generated

Asciidoctor:: A fast text processor & publishing toolchain for converting AsciiDoc to HTML

Usage

output = formatter.linkToPage("AsciidocFormatterTest.html", "This is a link to a page");

Render

This is a link to a page

Asciidoc generated

link:AsciidocFormatterTest.html[This is a link to a page]

Usage

output = formatter.linkToPage("AsciidocFormatterTest.html", "AnchorExample", "This is a link to a page");

Render

This is a link to a page

Asciidoc generated

link:AsciidocFormatterTest.html#anchorexample[This is a link to a page]

Usage

output = formatter.linkToAnchor("AnchorExample", "This is a link to anchor in this page");

Render

This is a link to anchor in this page

Asciidoc generated

<<anchorexample,This is a link to anchor in this page>>

Usage

output = formatter.anchor("AnchorExample") + "You can make an anchor to here";

Render

You can make an anchor to here

Asciidoc generated

[[anchorexample]]You can make an anchor to here

List

One list item

Usage

output = formatter.listItem("First")
        + formatter.listItem("Second");

Render

  • First

  • Second

Asciidoc generated

* First
* Second

Full list

Usage

output = formatter.listItems("First", "Second", "Third");

Render

  • First

  • Second

  • Third

Asciidoc generated

* First
* Second
* Third

List with a title

Usage

output = formatter.listItemsWithTitle("List title", "First", "Second", "Third");

Render

List title

  • First

  • Second

  • Third

Asciidoc generated

.List title
* First
* Second
* Third

Empty list

When no items, listItems method return an empty string.

Usage

output = formatter.listItems();

Asciidoc generated

















Block






Warning




Usage








output = formatter.warning("Take care of that");








Render











Warning






Take care of that













Asciidoc generated








[WARNING]
====
Take care of that
====












Block id




A block id create an id in HTML file.
It can be used to define a style.






Usage
















Render






Asciidoc generated








[#myId]












Predefine blocks




You can select block type from one of the Block enum.






Block value available


    

  • 

    LITERAL
    

    • 

  • 

    CODE
    

    • 







Usage








output = formatter.blockBuilder(Formatter.Block.LITERAL)
        .title("Simple block")
        .content("Into the block")
        .build();








Render






Simple block




Into the block








Asciidoc generated








.Simple block
....
Into the block
....












Free block




Usage








output = formatter.blockBuilder("====")
        .title("Simple block")
        .content("Into the block")
        .build();








Render






Example 1. Simple block






Into the block










Asciidoc generated








.Simple block
====
Into the block
====












Escape asciidoc




To display asciidoc in a block, it’s necessary to escape some keyword
that are interpreted even in an uninterpreted block.






With this option, all lines starting by include:: add an anti-slash to escape this directive.






Usage








output = formatter.blockBuilder("----")
        .escapeSpecialKeywords()
        .content("include::MyFile.txt[]")
        .build();








Render








include::MyFile.txt[]








Asciidoc generated








----
\include::MyFile.txt[]
----
















Source






Source code




Usage








output = formatter.sourceCode(
        "public int add(int a, int b) {\n" +
                "   int result = a + b;\n" +
                "   return result;\n" +
                "}");








Render








public int add(int a, int b) {
   int result = a + b;
   return result;
}








Asciidoc generated








[source,java,indent=0]
----
public int add(int a, int b) {
   int result = a + b;
   return result;
}
----












Source code using a builder




Usage








output = formatter.sourceCodeBuilder("groovy")
        .title("Source code")
        .indent(4)
        .source(
                "public int add(int a, int b) {\n" +
                        "   int result = a + b;\n" +
                        "   return result;\n" +
                        "}")
        .build()
;








Render






Source code




    public int add(int a, int b) {
       int result = a + b;
       return result;
    }








Asciidoc generated








.Source code
[source,groovy,indent=4]
----
public int add(int a, int b) {
   int result = a + b;
   return result;
}
----












Source code using a minimal builder




Usage








output = formatter.sourceCodeBuilder()
        .source(
                "public int add(int a, int b) {\n" +
                        "   int result = a + b;\n" +
                        "   return result;\n" +
                        "}")
        .build()
;








Render








public int add(int a, int b) {
   int result = a + b;
   return result;
}








Asciidoc generated








[source,indent=0]
----
public int add(int a, int b) {
   int result = a + b;
   return result;
}
----
















Include






Include another file




Usage








final String fileToInclude = "tmp/anotherFile.adoc";
writeAFile(fileToInclude, "Text from another file included in this one");
output = formatter.include(fileToInclude);








Render






Text from another file included in this one






Asciidoc generated








include::tmp/anotherFile.adoc[]












Add a leveloffset




Usage








final String fileToInclude = "tmp/anotherFile.adoc";
writeAFile(fileToInclude, "Text from another file included in this one");
output = formatter.include(fileToInclude, 2);








Asciidoc generated








include::tmp/anotherFile.adoc[leveloffset=+2]












Include is agnostic of directory separator




Include directive always used '/' as directory separator regardless of operating system.
It allows to have same outputs when running tests in several environments.






Usage








output = String.join("\n",
        formatter.include("tmp/anotherFile.adoc"),
        "",
        formatter.include("tmp\\anotherFile.adoc"));








Asciidoc generated








include::tmp/anotherFile.adoc[]

include::tmp/anotherFile.adoc[]












Include with a tag




Usage








final String fileToInclude = "tmp/fileWithTag.adoc";
writeAFile(fileToInclude, String.join("\n",
        "Text with tag",
        "tag::myTag[]",
        "text inside tag",
        "end::myTag[]",
        "text after tag")
);
output = formatter.include_with_tag(fileToInclude, "myTag");








Render






text inside tag






Asciidoc generated








include::tmp/fileWithTag.adoc[tag=myTag]












Include with a range of lines




Usage








final String fileToInclude = "tmp/fileWithRange.adoc";
writeAFile(fileToInclude, String.join("\n",
        "* line 1",
        "* line 2",
        "* line 3",
        "* line 4",
        "* line 5")
);
output = formatter.include_with_lines(fileToInclude, 2, 4);








Render






    

  • 

    line 2
    

    • 

  • 

    line 3
    

    • 

  • 

    line 4
    

    • 







Asciidoc generated








include::tmp/fileWithRange.adoc[lines=2..4]
















Table






Display data




Usage








output = formatter.table(Arrays.asList(
        Arrays.asList("A", "B", "C"),
        Arrays.asList("x", "y", "z"),
        Arrays.asList("1", "2", "3")
));








Render














A


B


C






x


y


z






1


2


3









Asciidoc generated








|====
|A|B|C
|x|y|z
|1|2|3
|====












With an header




Usage








output = formatter.tableWithHeader(Arrays.asList(
        Arrays.asList("A", "B", "C"),
        Arrays.asList("x", "y", "z"),
        Arrays.asList("1", "2", "3")
));








Render













A
B
C







x


y


z






1


2


3









Asciidoc generated








|====
|A|B|C

|x|y|z
|1|2|3
|====












Header separate from data




Usage








output = formatter.tableWithHeader(
        Arrays.asList("A", "B", "C"),
        Arrays.asList(
                Arrays.asList("x", "y", "z"),
                Arrays.asList("1", "2", "3")
        ));








Render













A
B
C







x


y


z






1


2


3









Asciidoc generated








|====
|A|B|C

|x|y|z
|1|2|3
|====
















Attribute






Usage








output = formatter.attribute("MY_ATTRIBUTE", "The value");








Render






Asciidoc generated








:MY_ATTRIBUTE: The value














Image






Should add an image




Usage








output = formatter.image("doc_as_test.png");








Render







doc as test







Asciidoc generated








image::doc_as_test.png[]












Should add an image with title




With a title parameter, the text is shown when you mouse over the image.






Usage








output = formatter.image("doc_as_test.png", "doc as test");








Render






doc as test






Asciidoc generated








image:doc_as_test.png[title="doc as test"]