Wiki source code of XWiki Rendering Framework

Last modified by Vincent Massol on 2024/02/19 11:40

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 {{info}}
6 **Mission**: Transform some textual input content in a given syntax into an output content in another syntax.
7 {{/info}}
8
9 = General Architecture =
10
11 image:rendering-architecture-simple.png
12
13 * **{{scm project="xwiki-rendering" path="xwiki-rendering-api/src/main/java/org/xwiki/rendering/block/XDOM.java"}}XDOM{{/scm}}**: A Java object representing the input as a tree made of Java {{scm project="xwiki-rendering" path="xwiki-rendering-api/src/main/java/org/xwiki/rendering/block/Block.java"}}Block objects{{/scm}} (a.k. as an AST).
14 * **{{scm project="xwiki-rendering" path="xwiki-rendering-api/src/main/java/org/xwiki/rendering/parser/Parser.java"}}Parser{{/scm}}**: Parses some textual input in a given syntax and generate a XDOM object.
15 * **{{scm project="xwiki-rendering" path="xwiki-rendering-api/src/main/java/org/xwiki/rendering/renderer/Renderer.java"}}Renderer{{/scm}}**: Takes a XDOM as input and generates some output.
16 * **{{scm project="xwiki-rendering" path="xwiki-rendering-api/src/main/java/org/xwiki/rendering/transformation/Transformation.java"}}Transformation{{/scm}}**: Takes some XDOM and modifies it to generate a modified XDOM.
17
18 See [[Advanced Architecture>>Main.Architecture]] for more details.
19
20 = Features =
21
22 * Parsers for [[multiple syntaxes>>||anchor="HSupportedSyntaxes"]]. {{version since="13.3RC1"}}Parsers register the Syntax they support into a Syntax Registry{{/version}}.
23 * Offers both a streaming API (useful for rendering large content) and an XDOM-based API (generates an intermediary AST on which transformations - such as macros - can be applied)
24 * Round trip between [[XWiki Syntax 2.0>>Main.XWikiSyntax]] and XHTML. This features allows for example to have a strong WYSIWYG editor that doesn't loose information when editing wiki pages. Another use case is the ability to import Office documents in HTML and transform them into XWiki Syntax 2.0 without loosing information.
25 * Ability to get the result of the parsing as an AST tree (called XDOM) which can then be used to get access to all structured elements from the flat text input.
26 * Ability to transform the XDOM through a Transformation (list of of [[available Transformations>>Main.Transformations]]).
27 * Macro support (list of [[available Macros>>Main.Macros]]). Note that Macro support is implemented as a Transformation (see [[Architecture>>Main.Architecture]]).
28 * Supports wiki syntax in link labels even for input syntaxes that don't support it.
29 * Automatic conversion from any of the supported input syntaxes to XWiki Syntax 2.0 or to XHTML.
30 * Strong Parsers:
31 ** Based on Grammars (JavaCC)
32 ** Fix user mistakes (not closed or overlapping markup elements...).
33 ** Each block element (paragraph, table cells, list items, headers...) can spread over multiply lines.
34 ** Support for groups, i.e. ability to include content inside other content (equivalent of DIV in HTML).
35 ** All elements can have parameters associated to them.
36 * Been used in [[XWiki>>xwiki:Main.WebHome]] for several years and is stable and performant.
37 * Can be used standalone since it's independent of other XWiki projects such as XWiki Platform, etc.
38
39 The XWiki Rendering modules are all released under the [[LGPL license>>xwiki:Main.License]].
40
41 = Supported Syntaxes =
42
43 ; Input Syntax
44 : It means there's a Parser that can be used to parse this syntax into a XDOM object
45
46 ; Output Syntax
47 : It means there's a Renderer that can be used to render an XDOM into this syntax
48
49 |=Name|=Id|=Input Syntax?|=Output Syntax?|=Extension?|=Description
50 |[[XWiki 2.0>>XWiki.XWikiSyntax||queryString="syntax=2.0"]]|##xwiki/2.0##|(/)|(/)|(x)|
51 |[[XWiki 2.1>>XWiki.XWikiSyntax||queryString="syntax=2.1"]]|##xwiki/2.1##|(/)|(/)|(x)|
52 |XHTML 1.0|##xhtml/1.0##|(/)|(/)|(x)|
53 |XHTML 5|xhtml/5|(/)|(x)|(x)|Available in XWiki Rendering 14.1RC1+ only. This is the same as HTML 5.0 except that input must be valid XML.
54 |HTML 5.0|##html/5.0##|(/)|(/)|(x)|Available in XWiki Rendering 6.4+ only. Input syntax is available in XWiki Rendering 14.1RC1+ only.
55 |HTML 4.01|##html/4.01##|(/)|(/)|(x)|
56 |Plain Text|##plain/1.0##|(/)|(/)|(x)|Print all than can be rendered in a simple notepad-like editor such as words, special symbols and spaces. It also generates link labels for links that have no labels and print the generated labels. Last it provides very basic formatting (e.g. separates paragraphs with new lines and separates list items with new lines).
57 |[[DocBook 4.4>>http://www.docbook.org/specs/cd-docbook-docbook-4.4.html]]|##docbook/4.4##|(/)|(/)|(x)|Available in XWiki Rendering 3.2+ only.
58 |[[XDOM XML Current>>Syntax.XDOMXML]]|##xdom+xml/curent##|(/)|(/)|(x)|Available in XWiki Rendering 3.3+ only.
59 |[[XDOM XML 1.0>>Syntax.XDOMXML]]|##xdom+xml/1.0##|(/)|(/)|(x)|Available in XWiki Rendering 3.3+ only.
60 |[[XWiki 1.0>>XWiki.XWikiSyntax||queryString="syntax=1.0"]]|##xwiki/1.0##|(/)|(x)|(/)|
61 |[[Confluence 1.0>>extensions:Extension.Confluence.Syntax 10]]|##confluence/1.0##|(/)|(x)|(/)|Removed in 9.0. Should use 1.1 instead. See [[Confluence>>extensions:Extension.Confluence||anchor="H9.0"]].
62 |[[Confluence 1.1>>extensions:Extension.Confluence.Syntax 11]]|##confluence/1.1##|(/)|(x)|(/)|Moved to contrib in 9.0. See [[Confluence>>extensions:Extension.Confluence||anchor="H9.0"]].
63 |[[Confluence XHTML>>extensions:Extension.Confluence.Syntax XHTML]]|##confluence+xhtml/1.0##|(/)|(x)|(/)|Moved to contrib in 9.0. See [[Confluence>>extensions:Extension.Confluence||anchor="H9.0"]].
64 |JSPWiki|##jspwiki/1.0##|(/)|(x)|(x)|
65 |TWiki|##twiki/1.0##|(/)|(x)|(x)|
66 |LaTeX|tex/1.0|(x)|(/)|(x)|Removed in 10.2 and replaced by ##latex/1.0## (see below)
67 |[[MediaWiki 1.0>>MediaWikiSyntax]]|##mediawiki/1.0##|(/)|(x)|(/)|Deprecated and moved to [[the attic>>https://github.com/xwiki-attic/syntax-mediawiki-1.0]] in 8.2RC1.
68 |[[MediaWiki 1.6>>doc:extensions:Extension.MediaWiki.MediaWiki Syntax.WebHome]]|##mediawiki/1.6##|(/)|(x)|(/)|Comes with the new [[MediaWiki contrib project>>doc:extensions:Extension.MediaWiki.WebHome]].
69 |Creole 1.0|##creole/1.0##|(/)|(x)|(x)|
70 |[[Markdown 1.0>>extensions:Extension.MarkdownSyntax.Markdown Syntax 1\.0]]|##markdown/1.0##|(/)|(/)|(/)|Extracted out of XWiki starting 8.2M1. Output syntax supported starting with version 8.2 of the Markdown extension. Deprecated and remove in version 8.6 of the Markdown extension.
71 |[[Markdown 1.1>>extensions:Extension.MarkdownSyntax.Markdown Syntax 1\.1]]|##markdown/1.1##|(/)|(/)|(/)|Extracted out of XWiki starting 8.2M1. Adds syntax for macros, superscript and subscript support over Markdown 1.0 syntax. Output syntax supported starting with version 8.2 of the Markdown module. Deprecated and remove in version 8.6 of the Markdown extension.
72 |[[Markdown 1.2>>extensions:Extension.MarkdownSyntax.Markdown Syntax 1\.2]]|##markdown/1.2##|(/)|(/)|(/)|Added in version 8.4 of the Markdown extension.
73 |[[GitHub-Flavored Markdown 1.0>>extensions:Extension.MarkdownSyntax.GitHub-Flavored Markdown Syntax 1\.0]]|##markdown+github/1.0##|(/)|(/)|(/)|Added in version 8.7 of the Markdown extension.
74 |[[APT>>http://maven.apache.org/doxia/references/apt-format.html]]|##apt/1.0##|(/)|(/)|(x)|Available in XWiki Rendering 4.3+ only.
75 |[[DokuWiki 1.0>>doc:extensions:Extension.DokuWiki.DokuWiki Syntax Parser.WebHome]]|##dokuwiki/1.0##|(/)|(x)|(/)|Comes with the new [[DokuWiki contrib project>>doc:extensions:Extension.DokuWiki.WebHome]]
76 |[[LaTeX 1.0>>doc:extensions:Extension.LaTeX.Syntax 1\.0.WebHome]]|##latex/1.0##|(x)|(/)|(/)|Added as a [[Contrib Extension>>doc:extensions:Extension.LaTeX.WebHome]].
77 |[[Annotated XHTML>>doc:Syntax.HTMLVariants.WebHome||anchor="HAnnotatedXHTML"]]|##annotatedxhtml/1.0##|(x)|(/)|(x)|Used internally for the WYSIWYG editor (to keep track of Macros)
78 |[[Annotated HTML5>>doc:Syntax.HTMLVariants.WebHome||anchor="HAnnotatedHTML5"]]|##annotatedhtml5/1.0##|(x)|(/)|(x)|Used internally for the WYSIWYG editor (to keep track of Macros)
79 |[[AsciiDoc 1.0>>doc:extensions:Extension.AsciiDoc Syntax 1\.0.WebHome]]|##asciidoc/1.0##|(/)|(x)|(/)|[[AsciiDoctor Syntax>>https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/]].
80
81 = Demo =
82
83 {{include document="Main.Demo.WebHome"/}}
84
85 = Documentation =
86
87 * [[Getting started tutorial>>Main.GettingStarted]]
88 * [[Javadocs>>JavaDoc]]
89 * [[Advanced Architecture>>Main.Architecture]]
90 * [[Extending XWiki Rendering>>Main.Extending]]
91 * [[Available Macros>>Main.Macros]]
92 * [[Available Transformations>>Main.Transformations]]
93 * {{version since="13.3"}}[[Available Syntaxes>>Main.Syntaxes]]{{/version}}
94 * {{version since="14.0"}}[[Error Reporting>>Main.ErrorReporting]]{{/version}}
95
96 = Download =
97
98 Check the [[getting started tutorial>>Main.GettingStarted]] which contains all information to access the XWiki Rendering binaries.
99
100 Source files are available {{scm project="xwiki-rendering"}}here{{/scm}}.
101
102 = Projects using XWiki Rendering =
103
104 * [[XWiki>>xwiki:Main.WebHome]]: of course...
105 * [[eXo Platform>>http://www.exoplatform.com/company/en/home]]: Uses both the XWiki Rendering and the XWiki WYSIWYG Editor to provide a simple wiki inside their tools
106 * [[Wikbook>>http://code.google.com/p/wikbook/]]: Uses XWiki Rendering to generate DocBook from content written using a wiki syntax
107 * [[Jahia>>http://www.jahia.com/cms/home.html]]: Uses XWiki Rendering in its [["Jahia Wiki module">>http://www.jahia.com/community/documentation/jahiapedia/jahia-modules/wiki/wiki.html]]
108 * [[Grails XWiki Rendering Plugin>>https://github.com/literalice/grails-xwiki-rendering]]: Grails plugin that allows to convert text using the XWiki Rendering Framework.
109
110 = Alternatives =
111
112 Here are some libraries similar to XWiki Rendering in purpose:
113
114 * [[WikiModel>>http://code.google.com/p/wikimodel/]]: XWiki Rendering actually uses WikiModel and extends it. Note that since WikiModel wasn't active anymore, the XWiki project has forked it and incorporated it in its own sources.
115 * [[Eclipse Mylyn WikiText>>http://wiki.eclipse.org/Mylyn/Incubator/WikiText]]
116 * [[Maven Doxia>>http://maven.apache.org/doxia/index.html]]: Note that XWiki Rendering has a basic bridge to Doxia
117 * [[Sweble>>http://sweble.org]] provides a MediaWiki syntax parser and renderer (see [[Sweble 2.0 architecture>>http://sweble.org/2014/09/sweble-2-0-released/]].
118 * [[MediaWiki Parsers>>https://www.mediawiki.org/wiki/Alternative_parsers]].
  • Powered by XWiki 14.10.18-node1. Hosted and managed by XWiki SAS

Get Connected