The Wiki Markup conversion allows certain features to be enabled that will improve the conversion’s fidelity. These are off by default because we are still in the stage of verifying compatibility with the Content Service’s implementation of these conversions, and keeping exact feature parity (bugs and all) helps with that effort. However, once the dust settles, we have the option of enabling these features to fix known problems in the original implementation.

Although given with their short names here, the string lookup key for a flags uses its fully qualified class name. For example, the feature flag listed here as LinkEncoder.USE_TITLE uses the feature key com.atlassian.adf.wiki.encoder.marks.LinkEncoder.USE_TITLE.

WARNING: This naming convention is expected to change in the near future to support Atlassian’s internal migration to Statsig for feature flag support. Their API does not permit full stop (.) characters in feature flag keys. As a result, all of the . characters will soon be replaced by hyphens (-). Consumers that need to control feature flag states are advised to check the ChangeLog when upgrading to ensure that they know whether or not this change has taken effect so that they can update any feature flag keys that they currently rely upon.

Current: com.atlassian.adf.wiki.encoder.marks.LinkEncoder.USE_TITLE
Future: com-atlassian-adf-wiki-encoder-marks-LinkEncoder-USE_TITLE

Encoder feature flags

The following feature flags modify the ADF-to-Wiki encoder's behavior:

LinkEncoder.USE_TITLE – Links in wiki markup may optionally include a title (tooltip) for the link, as in [link text|http://www.example.com|title]. The original conversion ignores this field, but the link mark supports a title attribute, and this flag enables mapping it accordingly.
MediaSingleEncoder.INHERIT_LAYOUT – The mediaSingle node has a mandatory layout attribute. The closest equivalent in wiki markup is providing an align= attribute for the media link, such as !image.jpg|align=right!. The TypeScript encoder does not do this, but this implementation can do it when this feature flag is enabled.
MediaSingleEncoder.INHERIT_LINK – The link attribute can be placed on media nodes, but it can also be placed on the mediaSingle wrapper for one. The TypeScript encoder drops them, but this library will use the wrapper's link if this flag is set.
OrderedListEncoder.RESTRICT_ORDEREDLIST_TO_START_AT_ORDER_ONE – Ordered lists do not have to start with 1. in ADF, but there is no way to represent another starting value in Wiki Markup. By default, this situation is handled by using an {adf} macro for lists that are affected by this, but setting this flag causes the starting value to be discarded instead.
TextEncoder.IMPROVED_ESCAPING – The TypeScript implementation only tries to escape macros, mentions, and media references when encoding text nodes. Other markup, such as *bold*, is rendered without any attempt to escape it, meaning that the original literal meaning is often lost. Setting this flag will enable a more advanced escaper that uses the parser's analysis of the text to detect markup that needs to be escaped.

Parser feature flags

The following feature flags modify the wiki-to-ADF parser's behavior:

BlockquoteParser.ALLOW_LINKS – Rollout flag for enabling lists (bulleted and ordered) within blockquotes in wiki-to-ADF conversion.
CommonMacroParser.USE_ESCAPES – There are three different styles of macros used in Wiki Markup. The original implementation does not respect the escaping conventions when looking for closing tags. Setting this flag will fix that.
- UNPAIRED – Examples: {anchor} and {loremipsum} (neither is supported). They do not surround content, so no attempt is made to find a matching closing tag for them.
- PAIRED_LITERAL – Examples: {noformat} and {code}. The first tag with no attributes and identical casing always matches them, so {Code:java} will match the first unescaped occurrence of {Code}. If it is escaped with a backslash character, as in \{Code}, then both the backslash and the tag are literal. It is not possible to include the matching tag sequence without a literal backslash before it, and it is not possible for the content to end with a literal backslash.
- PAIRED_MARKUP – Examples: {color} and {quote}. The escaping convention is the same as for {code} and {noformat}, except that the normal conventions in wiki markup for interpreting backslashes apply. For example, since { is an escapable character, a single backslash in \{color} will be removed.
LinkTextParser.CHECK_PREV_CHAR – The wiki renderer refuses to recognize a URL and turn it into a link when immediately preceded by one of the following characters, but the original implementation of the parser still did. This flag fixes that:
- ' or " – Don't mark a link if somebody put it in quotes.
- [ or | – Would have been parsed under the [text|url] link parser syntax if that were what we wanted. Getting here means that it must have failed to parse as a link and must instead be handled as a fallback, so it should stay text.
- ! – Would have been parsed under the !url! media parser syntax if that were what we wanted.
ListBuilder.OMIT_ORDER – On orderedList elements, the order attribute is optional and defaults to 1, but the TypeScript implementation always sets an explicit value for it. This flag suppresses the redundant value from the ADF output.
MediaParser.PARSE_ALIGN_ATTR – The parser's side of the align= convention enabled by MediaSingleEncoder.INHERIT_LAYOUT.
MentionLinkResolved.OMIT_EMPTY_ATTRIBUTES – The text and accessLevel attributes on mention nodes are optional. Instead of omitting them, the TypeScript code explicitly sets them to empty strings, and this library mimics that behaviour for compatibility testing. Setting this flag disables that, allowing the unnecessary attributes to be omitted from the resulting ADF.
QuoteMacroParser.ALLOW_NEW_CONTENT – Rollout flag for enabling codeBlock and media nodes within blockquotes in wiki-to-ADF conversion (ADF Change 80).
TableParser.OMIT_TABLE_ATTRIBUTES – The TypeScript version of the wiki conversion code includes optional attributes with their default values explicitly. This is unnecessary, but this library preserves that behaviour for compatibility testing reasons. Enabling this feature flag disables this, allowing the unnecessary attributes to be omitted from the resulting ADF.
UrlLinkResolver.IMPROVED_LINKS – Enables two enhancements to how the link mark is applied to the content inside a [content|url] link:
- The link can be applied to image content as well as text nodes.
- The extra copy of the original link text is only added if none of the content could be linked to the target. If anything is successfully linked to it (or found to already have been marked with the link), then the extra text is not added.