Markdown Limitations
Explanation
XWiki doesn't keep the Markdown text of a page as you typed it when the page is edited with the WYSIWYG editor. It reads the Markdown into its own content model, lets you edit that model, and writes it back as Markdown when you save:
Markdown can't express everything the XWiki content model can hold, so this round trip can change the Markdown text, and sometimes loses content. Some Markdown constructs are also not supported at all.
Changes made by the WYSIWYG editor
Some changes only rewrite the Markdown text: the page displays the same.
| Content | Markdown before | Markdown after saving |
|---|---|---|
| Italics and bold | *world* and __strong__ | _world_ and **strong** |
| Table | | a | b |
|---|---| | | a | b |
| --- | --- | |
Others lose content:
| Content | Markdown before | Markdown after saving |
|---|---|---|
| Ordered list starting at another number than 1 | 3. three
4. four | 1. three
1. four |
| HTML tags other than div around Markdown content, on their own lines (MARKDOWN-93) | <section class="red">
*x*
</section> | <section class="red"> |
Formatting that you apply in the WYSIWYG editor and that Markdown can't express is lost when you save: text color, text alignment, image size and merged table cells. A list or another block inside a table cell breaks the table.
Markdown Syntax 8.10.0+ Boxes, such as an information box added from the "Styles" list, and div tags around Markdown content are kept as groups. To wrap Markdown content in HTML, use a div.
Unsupported Markdown
| Markdown | Example | Displayed as |
|---|---|---|
| Footnotes | Text[^1]
[^1]: A footnote | The text as typed |
| Backslash escape | a\*b | a\*b, instead of a*b |
| Link to a URL without a scheme | www.xwiki.org | A broken link: write https://www.xwiki.org |
See the unresolved Markdown issues for the other known limitations.
