The AdfParser interface is also provided by the module jira-builder-adf-wiki, which can render ADF to/from the legacy Wiki Markup format. This is a port of the AtlasKit @atlaskit/editor-wikimarkup-transformer module, which itself has large sections ported from the original Atlassian Wiki Renderer library. The TypeScript version of the code has its own parser and encoder implementations that are tied to the ProseMirror representation of ADF nodes. This library substitutes its own concrete nodes like Doc and Paragraph in their place.

This is more of an art than a science, and there are many known problems with the conversion code as it currently stands. ADF and Wiki Markup do not have feature parity, and there are many edge cases where it is difficult to find the correct representation of something or where it is outright impossible to preserve the output without significant changes. In general, converting to or from Wiki Markup is lossy; the content often does not reliably round-trip.

Conversions should be avoided when possible. When it is not possible to avoid them entirely, our recommendation is to pick a single format to be authoritative (preferably ADF) and only perform conversions in a single, consistent direction so that the behavior remains predictable.

Simple Example

Let’s convert a very simple Wiki Markup example that has no external dependencies to complicate things. We will work with this Wiki Markup:

Wiki

1
2
Hello *world*!

Java

We just need to create the transformer, and the transformer needs access to a JSON parser. This is so that the transformer can process {adf} macros, which protect ADF structures that are impossible to represent in wiki markup so that they will not be damaged if the conversion is reversed. We can get a JSON parser from any of the ADF parsers. This example assumes that Jackson v2 is used:

1
2
3
4
5
6
        String wiki = "Hello *world*!";
        AdfJackson2 adfJackson2 = new AdfJackson2();
        WikiMarkupTransformer transformer = WikiMarkupTransformer.using(adfJackson2.jsonParser());
        Doc adf = transformer.parse(wiki);
        System.out.println(adfJackson2.pretty().marshall(adf));

Result

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "type" : "doc",
  "version" : 1,
  "content" : [ {
    "type" : "paragraph",
    "content" : [ {
      "type" : "text",
      "text" : "Hello "
    }, {
      "type" : "text",
      "text" : "world",
      "marks" : [ {
        "type" : "strong"
      } ]
    }, {
      "type" : "text",
      "text" : "!"
    } ]
  } ]
}

Further Information

Conversion Context – what to do for more complicated content
Feature Flags - enabling experimental features