Wiki source code of Syntax Conversion
Version 2.8 by Eleni Cojocariu on 2025/06/20
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | = Converting the Content Automatically = | ||
| 6 | |||
| 7 | If you already have content for a Page in a given [[Syntax>>xwiki:XWiki.XWikiSyntax]] and you try to [[change the Syntax>>xwiki:XS.XWikiStandardFlavor.UserGuide.PageLifecycle.ChangeSyntax.WebHome]] to another one, then XWiki will propose to convert your content to the new Syntax, if it knows how to perform that conversion (i.e. if there is a [[Parser>>rendering:Main.WebHome||anchor="HSupportedSyntaxes"]] available for the old Syntax and a [[Renderer>>rendering:Main.WebHome]] available for the new Syntax). For instance, switching to the XWiki Syntax 2.0+ will always prompt for a conversion. | ||
| 8 | |||
| 9 | If you accept the Syntax conversion, by clicking "Yes", then XWiki will update the content with the result of the conversion. The quality of the conversion will usually be good but may depend on the quality of the original Syntax. You need to review the quality of the conversion by checking for [[conversion errors>>xwiki:Documentation.UserGuide.Features.DocumentLifecycle.SyntaxConversion.WebHome||anchor="HConversionErrors"]] that can appear. | ||
| 10 | |||
| 11 | = Conversion Errors = | ||
| 12 | |||
| 13 | Some examples of conversion errors are: | ||
| 14 | |||
| 15 | * broken links | ||
| 16 | * style issues | ||
| 17 | * table formatting issues | ||
| 18 | * structure issues | ||
| 19 | |||
| 20 | For example, converting from XWiki Syntax 2.1 to CommonMark Markdown Syntax 1.2 leads to: | ||
| 21 | |||
| 22 | {{gallery}} | ||
| 23 | image:BeforeSyntaxConversion.png | ||
| 24 | image:SyntaxConversionErrors.png | ||
| 25 | {{/gallery}} | ||
| 26 | |||
| 27 | The "Getting started" link is broken after the conversion because of a bug in the conversion to CommonMark Markdown Syntax 1.2. Another possibe issue is that some Syntaxes don't have a way to express some structures. In the example above, CommonMark Markdown Syntax 1.2 has no native support for columns and thus the conversion is not perfect. | ||
| 28 | |||
| 29 | = Converting the Content Manually = | ||
| 30 | |||
| 31 | Rejecting the Syntax conversion, by clicking "No", will only change the Syntax identifier, letting you do the Syntax conversion of the content by yourself. This means that you will need to manually rewrite the content in the selected Syntax. The same will happen if the Syntax conversion is not possible. | ||
| 32 | |||
| 33 | {{image reference="SyntaxConversionUnsupported.png" size="large"/}} |
