The content on webpages is generally represented in a language called HTML, which stands for HyperText Markup Language. This is a fairly verbose and unforgiving presentation language that is difficult to read “at a glance”. In the early days of the Internet, very few options were available for editing web page content, and these generally required the web page’s author to understand HTML well enough to write content in it directly.
In the early 2000s, the concept of user-friendly and more human-readable wiki languages grew in popularity. In these earlier days, there were no standards for how to represent the content. Bold text might be represented as *bold*, **bold**, or '''bold'''. A level 3 heading might be h3. Heading, ### Heading, or === Heading ===. Over the following 20 years, the world largely converged on two major frontrunners:
Atlassian Wiki Markup is neither of these. Due to the accidents of history, it was developed shortly after MediaWiki and shortly before Markdown. Atlassian originally created it to use for the data storage format in Confluence, and Jira soon adopted it to enhance the presentation of issue descriptions and comments.
Although the Atlassian Wiki Markup format is quite flexible, it has several awkward characteristics that can make life more difficult for users. Some examples of this include inconsistencies with how backslash (\) characters are treated and mismatches between Atlassian Wiki Markup and the similar but now more popular Markdown format, which Atlassian itself also uses in other products like Bitbucket.
To reduce the impact of this annoying mismatch, Atlassian developed WYSIWYG editors for Jira and Confluence. Confluence went further, migrating its internal storage format to an XHTML syntax (often called CHTML to indicate the use of Confluence-specific tags in it), but Jira never moved away from the use of Wiki Markup in the Server and Data Center product lines.
Beginning in 2018, Jira Cloud began adopting ADF to help improve the flexibility of the editing experience and interoperability with other Atlassian Cloud products. However, the Wiki Markup syntax is still used by several public APIs and must also be understood when customers migrate from Jira Server or Jira Data Center to Jira Cloud.
It is unlikely that this migration problem will ever be entirely resolved, so Jira Cloud is likely to have to continue to accept Wiki Markup for many years to come, at least during the import process. However, many of the public APIs have already been updated to support ADF, and this is the intended future direction of all public APIs for Jira Cloud. The Atlassian Wiki Markup data format should therefore be considered a legacy format for Jira Cloud and new code should not use it.
The primary motivation behind this adf-builder-java library is to provide developers (both internally at Atlassian and externally in the Ecosystem) who write code in Java (or Kotlin) the tools that they need to author ADF directly so that they can successfully move away from using Atlassian Wiki Markup.
adf-builder-java-wiki ModuleThe same AdfParser interface that decorates this library for cleaner integration with third-party JSON libraries is also implemented by the jira-builder-adf-wiki module. For that module, the String format used is the legacy Atlassian Wiki Markup format instead of JSON.
The module is a port of the @atlaskit/editor-wikimarkup-transformer TypeScript 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 uses its own concrete nodes in their place.
Conversion between Atlassian Wiki Markup and ADF 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, so conversion should be avoided whenever possible.
To keep the output consistent with the TypeScript implementation of the conversion code, several bugs or inaccuracies present in the conversion code have workarounds that are already coded into this library, but not enabled by default.
Rate this page: