Developer
News and Updates
Get Support
Sign in
Get Support
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Last updated Sep 1, 2026

Known Wiki Markup conversion bugs

Technical GuideConversion

These are problems that are known to exist and are difficult enough to solve that no solution has yet been implemented, not even behind a feature flag. These are generally indicated by tests that are @Disabled with a comment that briefly explains the problem.

  • Encoder: Macros: Unknown macros are never escaped. This is intentional, with the thinking being that if they aren’t recognized, they will get rendered as {macro} anyway. The problem is that when the macro is unknown, the Wiki Renderer does not know whether the macro would have represented block or inline content and assumes it should be treated as a block, which is far more disruptive to the rendering. If the unknown macro is escaped, it is correctly displayed as ordinary inline text.
  • Encoder: Text: There are contexts in which a given sequence of characters is absolutely impossible to encode in wiki markup. An example of this is that it is impossible to place the sequence hello {code} world in the middle of a {code} macro, because the only way to stop it from ending the code block prematurely is to alter the case or to put a backslash before it, and such a backslash would then be included literally as well. When the feature flag TextEncoder.IMPROVED_ESCAPING is enabled, we work around this by inserting an invisible U+2060 (WORD JOINER) character in the middle of it, and the same is done for that same case in {noformat} blocks. Probably a worse example involves doubled backslashes (\\) which are usually interpreted as a line break and yet still escape the character that follows. This causes all kinds of problems that this flag again uses a word joiner to work around.
  • Encoder: Marks: Mid-word marks should be enclosed in curly braces upon encoding. For example, “text boldnormal” should encode to text *bold{*}normal. The parser supports this, but the encoder has not yet been updated. The current behaviour matches the Atlassian frontend wikimarkup transformer.
  • Parser: Marks: Does not keep scanning if an unusable closing mark is found. For example, *foo * bar* should render as foo * bar, with a literal asterisk included in the middle of bold text. However, the parser is currently confused by the fact that there is whitespace before that candidate stop character, does not find the correct stop character at the end, and renders the whole thing as the unmarked text: *foo * bar*.
  • Parser: Media: The !media! link syntax is overeager and often matches things that it should not match, like !?!. This is probably because the wiki renderer uses a very complicated regular expression for this and the parser takes a much simpler approach to scanning for them.
  • Parser: Media: The !media! link syntax should generally be mapped to a mediaInline node and grouped together with text and other such inline nodes to make paragraphs. However, they are instead formed into their own groups and always surfaced as mediaSingle or mediaGroup block nodes instead.
  • Parser: Text: There is currently no logic in the parser to reverse the word-joiner workarounds that are enabled via the TextEncoder.IMPROVED_ESCAPING flag, and the wiki renderer and ADF rendering will both include the word joiner in their respective rendered outputs, meaning that copying and pasting such segments will not work as expected after a round-trip or export to Data Center. The invisible character may also make it more difficult for users to understand what is wrong.
  • Parser: URLs: The url parsing should fly over all markup characters so that things like http://www.atlassian.com/test/-hyphen-/file.txt do not get incorrectly interpreted as having strikethrough text in the middle of it. I have not looked into how hard it would be to fix that, yet.
  • Parser: URLs: The URI delimeter characters that have special meaning in the URI syntax (like : and [) are supposed to be %-encoded when present in other parts of the URL, such as the path or query fields. However, Javascript and Wiki Markup both allow them to be used like this without explicitly escaping them. Java is stricter and will reject such a URI as invalid, causing bare links with that syntax not to be recognized as URIs at all.

Rate this page: