Wiki source code of Markdown Limitations

Last modified by Eleni Cojocariu on 2026/11/13 12:29

Show last authors
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 ' ---- XWiki accessible diagram palette (WCAG 2.1 AA): paste verbatim under
7 ' !theme bluegray. Canonical copy: xwiki-doc-writing/tools/ in xwiki-dev-llm.
8 skinparam activity {
9 BackgroundColor #0568AE
10 BorderColor #034873
11 FontColor #FFFFFF
12 StartColor #04538B
13 EndColor #04538B
14 BarColor #5A5A5A
15 ' Diamonds are blue with white text, not light with dark text: a labelled
16 ' `repeat :x;` takes its fill from DiamondBackgroundColor but its font from
17 ' FontColor above, so a light fill draws that one box white on white, and no
18 ' selector reaches it without reaching the decision diamonds too.
19 DiamondBackgroundColor #0568AE
20 DiamondBorderColor #034873
21 DiamondFontColor #FFFFFF
22 }
23 skinparam state {
24 BackgroundColor #0568AE
25 BorderColor #034873
26 FontColor #FFFFFF
27 AttributeFontColor #FFFFFF
28 StartColor #04538B
29 EndColor #04538B
30 }
31 skinparam class {
32 BackgroundColor #0568AE
33 BorderColor #034873
34 FontColor #FFFFFF
35 HeaderBackgroundColor #0568AE
36 AttributeFontColor #FFFFFF
37 StereotypeFontColor #262626
38 }
39 skinparam object {
40 BackgroundColor #0568AE
41 BorderColor #034873
42 FontColor #FFFFFF
43 AttributeFontColor #FFFFFF
44 StereotypeFontColor #262626
45 }
46 skinparam participant {
47 BackgroundColor #0568AE
48 BorderColor #034873
49 FontColor #FFFFFF
50 }
51 skinparam actor {
52 BackgroundColor #F5F5F5
53 BorderColor #5A5A5A
54 FontColor #262626
55 }
56 skinparam component {
57 BackgroundColor #0568AE
58 BorderColor #034873
59 FontColor #FFFFFF
60 }
61 skinparam collections {
62 BackgroundColor #0568AE
63 BorderColor #034873
64 FontColor #FFFFFF
65 }
66 skinparam queue {
67 BackgroundColor #0568AE
68 BorderColor #034873
69 FontColor #FFFFFF
70 }
71 skinparam stack {
72 BackgroundColor #0568AE
73 BorderColor #034873
74 FontColor #FFFFFF
75 }
76 ' database, control, entity, boundary and interface draw their label beside or
77 ' under the icon, on the page, in some diagram types: their text stays dark.
78 skinparam database {
79 BackgroundColor #F5F5F5
80 BorderColor #5A5A5A
81 FontColor #262626
82 }
83 skinparam control {
84 BackgroundColor #0568AE
85 BorderColor #034873
86 FontColor #262626
87 }
88 skinparam entity {
89 BackgroundColor #0568AE
90 BorderColor #034873
91 FontColor #262626
92 }
93 skinparam boundary {
94 BackgroundColor #0568AE
95 BorderColor #034873
96 FontColor #262626
97 }
98 skinparam usecase {
99 BackgroundColor #0568AE
100 BorderColor #034873
101 FontColor #FFFFFF
102 StereotypeFontColor #FFFFFF
103 }
104 skinparam card {
105 BackgroundColor #04538B
106 BorderColor #034873
107 FontColor #FFFFFF
108 }
109 skinparam note {
110 BackgroundColor #04538B
111 BorderColor #034873
112 FontColor #FFFFFF
113 }
114 skinparam storage {
115 BackgroundColor #8A4A00
116 BorderColor #8A4A00
117 FontColor #FFFFFF
118 }
119 skinparam agent {
120 BackgroundColor #8A4A00
121 BorderColor #8A4A00
122 FontColor #FFFFFF
123 }
124 skinparam interface {
125 BackgroundColor #A62222
126 BorderColor #A62222
127 FontColor #262626
128 }
129 skinparam node {
130 BackgroundColor #F5F5F5
131 BorderColor #5A5A5A
132 FontColor #262626
133 }
134 skinparam cloud {
135 BackgroundColor #F5F5F5
136 BorderColor #5A5A5A
137 FontColor #262626
138 }
139 skinparam artifact {
140 BackgroundColor #F5F5F5
141 BorderColor #5A5A5A
142 FontColor #262626
143 }
144 skinparam file {
145 BackgroundColor #F5F5F5
146 BorderColor #5A5A5A
147 FontColor #262626
148 }
149 skinparam rectangle {
150 BackgroundColor #FFFFFF
151 BorderColor #5A5A5A
152 FontColor #262626
153 StereotypeFontColor #0568AE
154 }
155 skinparam folder {
156 BackgroundColor #F5F5F5
157 BorderColor #8A4A00
158 FontColor #8A4A00
159 }
160 skinparam frame {
161 BackgroundColor #F5F5F5
162 BorderColor #04538B
163 FontColor #04538B
164 }
165 skinparam package {
166 BackgroundColor #FFFFFF
167 BorderColor #0568AE
168 FontColor #262626
169 }
170 skinparam partition {
171 BackgroundColor #FFFFFF
172 BorderColor #0568AE
173 FontColor #0568AE
174 }
175 skinparam swimlane {
176 BorderColor #0568AE
177 TitleBackgroundColor #F5F5F5
178 TitleFontColor #0568AE
179 }
180 skinparam sequence {
181 BoxBackgroundColor #F5F5F5
182 BoxBorderColor #5A5A5A
183 BoxFontColor #262626
184 DelayFontColor #262626
185 GroupBorderColor #5A5A5A
186 GroupFontColor #262626
187 LifeLineBorderColor #5A5A5A
188 LifeLineBackgroundColor #F5F5F5
189 TitleFontColor #0568AE
190 StartColor #0568AE
191 EndColor #0568AE
192 BorderColor #0568AE
193 }
194 skinparam arrow {
195 Color #0568AE
196 FontColor #262626
197 }
198 skinparam legend {
199 BackgroundColor #F5F5F5
200 BorderColor #5A5A5A
201 FontColor #262626
202 }
203 skinparam stereotype {
204 CBackgroundColor #F5F5F5
205 CBorderColor #5A5A5A
206 ABackgroundColor #F5F5F5
207 ABorderColor #5A5A5A
208 IBackgroundColor #F5F5F5
209 IBorderColor #5A5A5A
210 EBackgroundColor #F5F5F5
211 EBorderColor #5A5A5A
212 NBackgroundColor #F5F5F5
213 NBorderColor #5A5A5A
214 }
215 skinparam ArrowColor #0568AE
216 ' titleFontColor only: the nested `skinparam title { BackgroundColor }` form
217 ' leaks its background onto every element in the diagram.
218 skinparam titleFontColor #0568AE
219 skinparam titleBorderColor #5A5A5A
220 ' Links otherwise take bluegray's white root colour, unreadable on a light fill.
221 <style>
222 root {
223 HyperLinkColor #0568AE
224 }
225 element {
226 HyperLinkColor #FFFFFF
227 }
228 actor, artifact, boundary, cloud, control, database, entity, file, folder, frame, interface,
229 legend, node, package, rectangle {
230 HyperLinkColor #0568AE
231 }
232 </style>
233 ' ---- end XWiki accessible diagram palette ----
234 left to right direction
235 rectangle "Markdown\nof the page" as src
236 rectangle "XWiki content" as model
237 rectangle "WYSIWYG\neditor" as editor
238 rectangle "Markdown\nsaved" as out
239 src --> model : read
240 model --> editor : edit
241 editor --> out : save
242 @enduml
243 {{/plantuml}}
244
245 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.
246
247 == Changes made by the WYSIWYG editor ==
248
249 Some changes only rewrite the Markdown text: the page displays the same.
250
251 |=Content|=Markdown before|=Markdown after saving
252 |Italics and bold|{{code language="none"}}*world* and __strong__{{/code}}|{{code language="none"}}_world_ and **strong**{{/code}}
253 |Table|{{code language="none"}}| a | b |
254 |---|---|{{/code}}|{{code language="none"}}| a | b |
255 | --- | --- |{{/code}}
256
257 Others lose content:
258
259 |=Content|=Markdown before|=Markdown after saving
260 |Ordered list starting at another number than 1|{{code language="none"}}3. three
261 4. four{{/code}}|{{code language="none"}}1. three
262 1. four{{/code}}
263 |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">
264
265 *x*
266
267 </section>{{/code}}|{{code language="none"}}<section class="red">{{/code}}
268
269 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.
270
271 {{version product="Markdown Syntax" since="8.10.0"}}
272 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##.
273 {{/version}}
274
275 == Unsupported Markdown ==
276
277 |=Markdown|=Example|=Displayed as
278 |Footnotes|{{code language="none"}}Text[^1]
279
280 [^1]: A footnote{{/code}}|The text as typed
281 |Backslash escape|{{code language="none"}}a\*b{{/code}}|{{code language="none"}}a\*b{{/code}}, instead of {{code language="none"}}a*b{{/code}}
282 |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}}
283
284 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.

Get Connected