Advanced XWiki syntax examples

07 Nov 2019 5 min read

Written by

Oana Elena Florea

, Customer Support Manager

Article updated on 20 February 2020

XWiki pages are written by default using the XWiki syntax, a simple wiki syntax that can be used to format text, create tables, create links, display images, etc.

It is usually hidden for the user because it could be considered a bit too technical and not what you'd expect when dealing with multiple pages. Nonetheless, there are some knowledge management features relying on its direct usage (comments, macros, when using the wiki editor or the WYSIWYG Source tab, etc.) that will save you time and increase productivity. Note that the XWiki platform has included improvements, in newer versions, to help the user with the XWiki syntax - the possibility to edit macro content directly in the editor or copy-paste the generated page reference inside the "Information tab".

The advanced XWiki syntax examples below can help enhance the quality of your organization's information management.

Use the information tab to get the page reference

The XWiki page reference is a concept (also known as “entity”) that describes pages. The string representation of this concept can be sometimes very technical for the simple user. For example a simple URL such as http://<server>/xwiki/bin/view/Sandbox/TestPage1 can be translated to “Sandbox.TestPage1” (relative reference) or “xwiki:Sandbox.TestPage1” (absolute reference).
To help with the usage of page references when creating links to a page inside the wiki syntax editor, when using a page as a parameter to wiki macro, etc., the XWiki platform (starting with v11.1) includes a new feature inside the “Information” tab: the possibility to copy-paste the generated page reference.

page_reference.gif

Use the syntax to include attachment references

Attachment references are often used with macros including images or documents (e.g. {{gallery macro}}, {{pdfviewer}} macro, etc).

The general syntax for an attachment reference is Wiki:Space.Document@Filename.

This string representation of an attachment can be used with xwiki syntax for example when including an image from a different page inside a {{gallery}} macro:

GalleryMacro.png

Add formatting to comments

Comments are an essential feature of any collaboration tool. When adding comments inside XWiki you can use the XWiki syntax to enrich your content with text effects, lists, lines, tables, macros, quotations, emoticons, etc. For example a text like “Very nice blog post emoticon_smile! Could you send me a link to the **XWiki syntax documentation**?” will be “rendered” to replace :) with the emoticon, while “XWiki syntax documentation” will become bold.

Comment_XWikiSyntax.png

Bonus Tip: Using the “Preview” button you can easily check the content before adding the comment. The complete documentation for the XWiki syntax is available on xwiki.org.

Use XWiki syntax within macros

The XWiki platform includes macros for wiki content, formatting, navigation, notifications, layout, etc. When including macros like “box” in gadgets you can also add some XWiki syntax to enrich its content. The example below displays a table representing our support SLA.

XWikiDashboard_Syntax.png

Bonus Tip: You can take a look at the complete XWiki syntax documentation for tables here.

Create advanced links using XWiki syntax

Links are useful for connecting related information inside your wiki or building rich content. It’s easy to create a simple link with the XWiki syntax using the following definition: [[link label>>link URL]]. Things could get complicated if your need is more specific: to add parameters to the URL, to link an anchor or a heading in a page, a specific query or a page reference. For example, a link to the profile preferences section could look like this: [[My profile preferences>>XWiki.OanaFlorea||queryString="category=preferences"]]

Bonus Tip:  You can take a look at the complete XWiki syntax documentation for links available on xwiki.org.

Edit the page in “wiki” mode

The “wiki” mode is a simple editor that allows you to edit directly the XWiki syntax of your page. By default, the edition of a page will be done using the WYSIWYG editor. However, if you want strict control on the formatting of your page or you want to “play” with the XWiki syntax you can use the “wiki” editor (just click on Edit>Wiki from the content menu). This editor is available for the “advanced” users only, thus you need to update the “User Type” preference on your wiki profile accordingly.

WikiEditor.png

Bonus Tip: If you are very comfortable with the “wiki” mode and you want to keep it as a default, you can update the “Default editor” to “Text”.

Where can I find the XWiki syntax guide?

The XWiki syntax guide is included as a page on each wiki and you can access it:

  • Using the default URL http://<server>/xwiki/bin/view/XWiki/XWikiSyntax?xpage=print.
  • When editing in wiki mode, the right panel "XWiki Syntax Help" will include a link to the guide.

You can also find the XWiki syntax guide online on xwiki.org

General FAQ

What is wiki syntax?

The wiki syntax is the default markup used by wiki engines to format a page.

What is the syntax used by XWiki?

The default markup language used by the XWiki platform to format a page is the XWiki syntax. The latest version is XWiki Syntax 2.1.

Can XWiki support other syntaxes?

The XWiki rendering engine supports multiple syntaxes, the full list is available on the documentation page.

What is the general syntax of a document reference?

The general string representation for a document is wiki:space.document. Other examples using relative references are included on the documentation page.

Do you want to know more about the uses of XWiki syntax? Let us know!

You may also be interested in:

News

Enhancing digital sovereignty: XWiki and Nextcloud forge closer ties

XWiki SAS has long upheld its commitment to independence, with shareholders exclusively comprising current and former employees. However, recognizing the importance of strong collaboration among major open-source projects in the EU, the company is embracing a strategic shift through a symbolic investment in XWiki SAS from Frank Karlitschek, Founder and CEO of Nextcloud. Moreover, Nextcloud GmbH and XWiki SAS have signed a mutual resellers' agreement to provide their customers an easy way to purchase a complete solution from either vendor. Read the full article to learn about the why, how, and what.