Wiki source code of Markdown Limitations
Last modified by Vincent Massol on 2026/09/28 14:37
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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: | ||
| 2 | |||
| 3 | {{plantuml}} | ||
| 4 | @startuml | ||
| 5 | !theme bluegray | ||
| 6 | left to right direction | ||
| 7 | rectangle "Markdown\nof the page" as src | ||
| 8 | rectangle "XWiki content" as model | ||
| 9 | rectangle "WYSIWYG\neditor" as editor | ||
| 10 | rectangle "Markdown\nsaved" as out | ||
| 11 | src --> model : read | ||
| 12 | model --> editor : edit | ||
| 13 | editor --> out : save | ||
| 14 | @enduml | ||
| 15 | {{/plantuml}} | ||
| 16 | |||
| 17 | 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. | ||
| 18 | |||
| 19 | == Changes made by the WYSIWYG editor == | ||
| 20 | |||
| 21 | Some changes only rewrite the Markdown text: the page displays the same. | ||
| 22 | |||
| 23 | |=Content|=Markdown before|=Markdown after saving | ||
| 24 | |Italics and bold|{{code language="none"}}*world* and __strong__{{/code}}|{{code language="none"}}_world_ and **strong**{{/code}} | ||
| 25 | |Table|{{code language="none"}}| a | b | | ||
| 26 | |---|---|{{/code}}|{{code language="none"}}| a | b | | ||
| 27 | | --- | --- |{{/code}} | ||
| 28 | |||
| 29 | Others lose content: | ||
| 30 | |||
| 31 | |=Content|=Markdown before|=Markdown after saving | ||
| 32 | |Ordered list starting at another number than 1|{{code language="none"}}3. three | ||
| 33 | 4. four{{/code}}|{{code language="none"}}1. three | ||
| 34 | 1. four{{/code}} | ||
| 35 | |HTML tags other than ##div## around Markdown content, on their own lines ([[MARKDOWN-93>>https://jira.xwiki.org/browse/MARKDOWN-93]])|{{code language="none"}}<section class="red"> | ||
| 36 | |||
| 37 | *x* | ||
| 38 | |||
| 39 | </section>{{/code}}|{{code language="none"}}<section class="red">{{/code}} | ||
| 40 | |||
| 41 | 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. | ||
| 42 | |||
| 43 | {{version product="Markdown Syntax" since="8.10.0"}} | ||
| 44 | Boxes, such as an information box added from the "Styles" list, and ##div## tags around Markdown content are kept as [[groups>>doc:documentation.extensions.user.markdown.syntax.WebHome||anchor="HGroups"]]. To wrap Markdown content in HTML, use a ##div##. | ||
| 45 | {{/version}} | ||
| 46 | |||
| 47 | == Unsupported Markdown == | ||
| 48 | |||
| 49 | |=Markdown|=Example|=Displayed as | ||
| 50 | |Footnotes|{{code language="none"}}Text[^1] | ||
| 51 | |||
| 52 | [^1]: A footnote{{/code}}|The text as typed | ||
| 53 | |Backslash escape|{{code language="none"}}a\*b{{/code}}|{{code language="none"}}a\*b{{/code}}, instead of {{code language="none"}}a*b{{/code}} | ||
| 54 | |Link to a URL without a scheme|{{code language="none"}}www.xwiki.org{{/code}}|A broken link: write {{code language="none"}}https://www.xwiki.org{{/code}} | ||
| 55 | |||
| 56 | See the [[unresolved Markdown issues>>https://jira.xwiki.org/issues/?jql=project%20%3D%20MARKDOWN%20AND%20resolution%20%3D%20Unresolved]] for the other known limitations. |
