XWikiSyntaxLinks

1

= Editing =

2

== Links ==

=== 1.0 Links ===

|=(% style="width:20%" %)Feature|=XWiki Syntax 1.0|=(% style="width:20%" %)Result

8

|Link to a page in the current Space|{{{[WebHome]}}}|[[Web Home>>WebHome]]

9

|Link with a label|{{{[label>WebHome]}}}|[[label>>WebHome]]

10

|Link with XWiki Syntax in the label|{{{<a href="$xwiki.getURL("WebHome")"><strong>bold label</strong></a>}}}|[[**bold label**>>WebHome]]

11

|Link to a page with the space specified|{{{[Main.WebHome]}}}|[[Web Home>>Main.WebHome]]

12

|Link to a subwiki|{{{[subwiki:Main.WebHome]}}}|[[Web Home>>xwiki:Main.WebHome]]

13

|Link that opens in a new window|{{{[label>WebHome>_blank]}}}|[[label>>WebHome||target="_blank"]]

14

|Link to a URL directly in the text|{{{This is a URL: https://xwiki.org}}}|This is a URL: https://xwiki.org

15

|Link to a URL|{{{[https://xwiki.org]}}}|[[https://xwiki.org]]

16

|Link to a URL with a label|{{{[XWiki>https://xwiki.org]}}}|[[XWiki>>https://xwiki.org]]

17

|Link to an email address|{{{[john@smith.net>mailto:john@smith.net]}}}|[[john@smith.net>>mailto:john@smith.net]]

18

|Image Link|{{{<a href="$xwiki.getURL("Space1.Page1")">{image:img.png|document=Space2.Page2}</a>}}}|[[image:XWiki.XWikiSyntaxLinks@img.png>>Main.WebHome]]

19

|Image Link with image parameters|{{{<a href="$xwiki.getURL("Space1.Page1")">{image:img.png|document=Space2.Page2|width=26|height=26}</a>}}}|[[[[image:XWiki.XWikiSyntaxLinks@img.png||width="26" height="26"]]>>Main.WebHome]]

20

|Link to an attachment on the current page|(((

21

{{info}}See [[Attach Macro>>https://extensions.xwiki.org/xwiki/bin/view/Extension/Old%20XWiki%201.0%20syntax%20renderer/Attach%20Macro%20%28Radeox%29]] for details{{/info}}

22

{{{{attach:text|file=img.png}}}}

23

)))|[[text>>attach:XWiki.XWikiSyntaxLinks@img.png]]

24

|Link to an attachment in a different page|(((

25

{{info}}See [[Attach Macro>>https://extensions.xwiki.org/xwiki/bin/view/Extension/Old%20XWiki%201.0%20syntax%20renderer/Attach%20Macro%20%28Radeox%29]] for details{{/info}}

26

{{{{attach:text|document=Space.Page|file=img.png}}}}

27

)))|[[text>>attach:XWiki.XWikiSyntaxLinks@img.png]]

28

|Link to an Anchor in a page|{{{[label>Space.Page#anchor]}}}|[[label>>XWiki.XWikiSyntax||anchor=anchor]]

29

|Link to a Heading in a page|(((

30

{{{[label>Space.Page#HMyheading]}}}

31

)))|[[label>>XWiki.XWikiSyntax||anchor=HMyheading]]

32

33

{{info}}When you add a Heading, an anchor named "H" followed by the heading title with only alpha characters is created. For example, for a Heading named "My heading", the generated anchor will be "HMyheading".{{/info}}

34

35

{{velocity}}$subHeading XWiki Syntax 1.0 Link Specification $subHeading{{/velocity}}

36

37

38

Part in ##( )## is required, parts in ##[ ]## are optional and one of the two chars in ##{ }## needs to be added if optional parts are being used.

39

40

41

The full format of a link is **##[label {> or |}] (resource) [@interWikiAlias] [{> or |} target]##**

42

43

* **##label##**: An optional string which will be displayed to the user as the link name when rendered. Example: ##My Page##

44

* **##resource##**: The full link reference using the following syntax: **##(reference) [?queryString] [#anchor]##**

45

** **##reference##**: The link reference. This can be either

46

*** **A URI** in the form **##protocol:path##** (examples: ##http:~/~/xwiki.org##, ##mailto~:john@smith.com##), or

47

*** **A wiki page** reference in the form **##~[~[wikiName:] spaceNameList.] (pageName)##**. Examples: ##WebHome##, ##Main.WebHome##, ##mywiki:Main.WebHome##

48

**** **##wikiName##**: An optional string containing the name of a wiki. The link will point to a page inside that wiki. Example: ##mywiki##

49

**** **##spaceNameList##**: An optional dot-separated list of wiki Space names. If no space is specified the current space is used. Examples: ##Main##, ##A.B##, ##A.B.C##

50

**** **##pageName##**: A required string containing the name of the linked wiki page. Example: ##WebHome##

51

** **##queryString##**: An optional query string for specifying parameters that will be used in the rendered URL. Example: ##mydata1=5&mydata2=Hello##

52

** **##anchor##**: An optional anchor name pointing to an anchor defined in the referenced link. Note that in XWiki anchors are automatically created for headings. Example: ##HTableOfContents##

53

* **##interWikiAlias##**: An optional [[Inter Wiki>>en.wikipedia.org/wiki/InterWiki]] alias as defined in the InterWiki Map (see the [[Admin Guide>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/]]). This is only valid for wiki page names. Example: ##wikipedia##

54

* **##target##**: An optional string corresponding to the Hhttps://TML ##target## attribute for a HTML ##A## link element. This element is used when rendering the link. It defaults to opening the link in the current window. Examples: ##_self##, ##_blank##

=== 2.0 Links ===

|=(% style="width:20%" %)Feature|=XWiki Syntax 2.0|=(% style="width:20%" %)Result

59

|Link to a page in the current Space|{{{[[WebHome]]}}}|[[WebHome]]

60

|Link with a label|(((

61

{{{[[label>>WebHome]]}}}

62

{{info}}XWiki Syntax is supported inside link labels.{{/info}}

63

)))|[[label>>WebHome]]

64

|Link with XWiki Syntax in the label|{{{[[**bold label**>>WebHome]]}}}|[[**bold label**>>WebHome]]

65

|Link to a page with the space specified|{{{[[Main.WebHome]]}}}|[[Main.WebHome]]

66

|Link to a subwiki|{{{[[subwiki:Main.WebHome]]}}}|[[xwiki:Main.WebHome]]

67

|Link that opens in a new window|{{{[[label>>WebHome||target="_blank"]]}}}|[[label>>WebHome||target="_blank"]]

68

|Link to a URL directly in the text|{{{This is a URL: https://xwiki.org}}}|This is a URL: https://xwiki.org

69

|Link to a URL|{{{[[https://xwiki.org]]}}}|[[https://xwiki.org]]

70

|Link to a URL with a label|{{{[[XWiki>>https://xwiki.org]]}}}|[[XWiki>>https://xwiki.org]]

71

|Link to an email address|{{{[[john@smith.net>>mailto:john@smith.net]]}}}|[[john@smith.net>>mailto:john@smith.net]]

72

|Image Link|{{{[[image:Space2.Page2@img.png>>Space1.Page1]]}}}|[[image:XWiki.XWikiSyntaxLinks@img.png>>Main.WebHome]]

73

|Image Link with image parameters|{{{[[[[image:Space2.Page2@img.png||width="26" height="26"]]>>Space1.Page1]]}}}|[[[[image:XWiki.XWikiSyntaxLinks@img.png||width="26" height="26"]]>>Main.WebHome]]

74

|Link to an attachment on the current page|{{{[[text>>attach:img.png]]}}}|[[text>>attach:XWiki.XWikiSyntaxLinks@img.png]]

75

|Link to an attachment in a different page|{{{[[text>>attach:Space.Page@img.png]]}}}|[[text>>attach:XWiki.XWikiSyntaxLinks@img.png]]

76

|Link to an Anchor in a page|{{{[[label>>Space.Page#anchor]]}}}|[[label>>XWiki.XWikiSyntax||anchor="anchor"]]

77

|Link to a Heading in a page|{{{[[label>>Space.Page#HMyheading]]}}}|[[label>>XWiki.XWikiSyntax||anchor="HMyheading"]]

78

|Link to an Anchor in the current page|{{{[[label>>#anchor]]}}}|[[label>>||anchor="anchor"]]

79

80

{{info}}When you add a Heading, an anchor named "H" followed by the heading title with only alpha characters is created. For example, for a Heading named "My heading", the generated anchor will be "HMyheading".{{/info}}

81

82

{{velocity}}$subHeading XWiki Syntax 2.0 Link Specification $subHeading{{/velocity}}

83

84

85

The part in ##( )## is required, while the parts in ##[ ]## are optional.

86

87

88

The full format of a link is **##[label>>] (resource) [@interWikiAlias] [||parameters]##**

89

90

* **##label##**: An optional string which will be displayed to the user as the link name when rendered. The label may contain XWiki Syntax. If no label is specified a default label will be generated. The generation pattern can be changed, see the [[Admin Guide>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/]]. Example: ##My Page##

91

* **##resource##**: The full link reference using the following syntax: **##(reference) [?queryString] [#anchor]##**

92

** **##reference##**: The link reference in one of the following forms:

93

*** **URL**: Any URL in the form of **##protocol:~/~/path##**. Examples: ##http:~/~/xwiki.org##, ##https:~/~/svn.xwiki.org/##

94

*** **Wiki page** reference in the form **##~[~[wikiName:] spaceNameList.] (pageName)##**. Examples: ##WebHome##, ##Main.WebHome##, ##mywiki:Main.WebHome##

95

**** **##wikiName##**: An optional string containing the name of a wiki. The link will point to a page inside that wiki. Example: ##mywiki##

96

**** **##spaceNameList##**: An optional dot-separated list of wiki Space names. If no space is specified the current space is used. Examples: ##Main##, ##A.B##, ##A.B.C##

97

**** **##pageName##**: A required string containing the name of the linked wiki page. Example: ##WebHome##

98

*** **Attachment** reference in the form **##attach~: [wikiPageName@] (attachmentName)##**. Examples: ##attach~:img.png##, ##attach~:mywiki:Main.WebHome@img.png##

99

**** **##attach~:##** A required string identifying the resource as attachment.

100

**** **##wikiPageName##**: An optional string referencing the page that holds the attachment, see "Wiki page" above.

101

**** **##attachmentName##**: Name of the attachment as it is stored in the wiki.

102

*** **Email address** in the form **##mailto~: (emailAddress)##** (###anchor## is not valid). Example: ##mailto~:john@smith.com##

103

**** **##mailto~:##** A required string identifying the resource as email.

104

**** **##emailAddress##**: Targeted email address. Example: "##john@smith.com##"

105

** **##queryString##**: An optional query string for specifying parameters that will be used in the rendered URL. Example: ##mydata1=5&mydata2=Hello##

106

** **##anchor##**: An optional anchor name pointing to an anchor defined in the referenced link. Note that in XWiki anchors are automatically created for headings and images. Example: ##HTableOfContents##

107

* **##interWikiAlias##**: An optional [[Inter Wiki>>https://en.wikipedia.org/wiki/InterWiki]] alias as defined in the InterWiki Map (see the [[Admin Guide>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/]]). This is only valid for wiki page names. Example: ##wikipedia##

108

* **##parameters##**: An optional list of parameters passed to the link. Example: ##target="~_blank"## (open in new window)

=== 2.1 Links ===

|=Feature|=XWiki Syntax 2.1|=Result

113

|Absolute link to page ##PageB## located in ##PageA##|{{{[[PageA.PageB]]}}}|[[PageB>>]]

114

|Relative link to page ##PageA## from the current page|{{{[[PageA]]}}} or {{{[[.PageA]]}}}|[[PageA>>]]

115

|Relative link to page ##PageB## in ##PageA## from the current page|{{{[[.PageA.PageB]]}}}|[[PageB>>]]

116

|Link with a label|(((

117

{{{[[label>>PageA]]}}}

118

119

{{info}}XWiki Syntax is supported inside link labels.{{/info}}

120

)))|[[label>>]]

121

|Link with wiki syntax in the label|{{{[[**bold label**>>PageA]]}}}|[[**bold label**>>]]

122

|Link on an image|{{{[[image:PageA@img.png>>PageA]]}}}|[[image:XWiki.XWikiSyntaxLinks@img.png>>]]

123

|Absolute link to page ##PageB## located in ##PageA## in wiki ##WikiA##|{{{[[WikiA:PageA.PageB]]}}}|[[PageB>>]]

124

|Link that opens in a new window|{{{[[PageA||target="_blank"]]}}}|[[PageA>>]]

125

|Implicit link to a URL|{{{This is a URL: https://xwiki.org}}}|This is a URL: https://xwiki.org

126

|Explicit link to a URL|{{{[[https://xwiki.org]]}}}|[[https://xwiki.org]]

127

|Explicit link to a URL with a label|{{{[[XWiki>>https://xwiki.org]]}}}|[[XWiki>>https://xwiki.org]]

128

|Link to an email address|{{{[[john@smith.net>>mailto:john@smith.net]]}}}|[[john@smith.net>>mailto:john@smith.net]]

129

|Link to an attachment on the current page|{{{[[attach:img.png]]}}}|[[img.png>>]]

130

|Link to an attachment in a different page|{{{[[attach:PageA.PageB@img.png]]}}}|[[img.png>>]]

131

|Link to an Anchor in a page|{{{[[PageA.PageB||anchor="anchor"]]}}}|[[PageB>>]]

132

|Link to a Heading in a page|(((

133

{{{[[PageA.PageB||anchor="HMyheading"]]}}}

134

135

{{info}}When you add a Heading, an anchor named "H" followed by the heading title with only alpha characters is created. For example, for a Heading named "My heading", the generated anchor will be "HMyheading".{{/info}}

136

)))|[[PageB>>]]

137

|Link to an anchor in the current page|{{{[[label>>||anchor="anchor"]]}}}|[[label>>]]

138

|Link to a page with a query string|{{{[[PageA.PageB||queryString="param1=value1&param2=value2"]]}}}|[[PageB>>]]

139

|Link to the current page with a query string|{{{[[label>>||queryString="param1=value1&param2=value2"]]}}}|[[label>>]]

140

141

{{velocity}}$subHeading XWiki Syntax 2.1 Link Specification $subHeading{{/velocity}}

142

143

144

Legend: The parts in ##()## are required, while the parts in ##[]## are optional.

145

146

147

The full format of a link is **##[label>>] (resource) [||parameters]##**

148

149

* **##label##**: An optional string which will be displayed to the user as the link name when rendered. The label may contain XWiki Syntax. If no label is specified a default label will be generated. The generation pattern can be changed, see the [[Admin Guide>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/]]. Example: ##My Page##

150

* **##resource##**: A required string with the link reference in one of the following forms

151

** **URL**: Any URL in the form of **##[url:](protocol:~/~/path)##**. Examples: ##http:~/~/xwiki.org##, ##url:https:~/~/svn.xwiki.org/##

152

*** **##url:##** An optional string identifying the resource as an URL.

153

*** **##protocol:~/~/path##**: The URL itself

154

** **Wiki page**: A reference in the form **##page:[(wikiName):](pageNameList)##**. Examples: ##page:Page##, ##page:myxwiki:Page##, ##page:ParentPage.ChildPage.SubChildPage##, ##page:../SiblingPage##, ##page:./ChildPage##

155

*** **##page:##** A required string identifying the resource as an XWiki page. The same reference can be used for either a terminal or non-terminal page, if both exist it will lead to the non-terminal page.

156

*** **##wikiName##**: An optional string containing the name of a wiki. The link will point to a page inside that wiki. If no wiki is specified, the current wiki is used. Example: ##mywiki##

157

*** **##pageNameList##**: A required list of slash-separated wiki Pages names pointing to the final linked wiki Page syntax. It's also possible to use ##.## and ##..## to indicate current or parent page/wiki. Examples: ##Main##, ##A/B##, ##A/B/C##, ##../Sibling##, ##./Child##

158

** **Wiki document**: A reference in the form **##[doc:]~[~[(wikiName):](spaceNameList).](documentName)##**. Examples: ##doc:Welcome##, ##doc:Main.Welcome##, ##doc:mywiki:Main.Welcome##, ##Welcome##

159

*** **##doc:##** An optional string identifying the resource as an XWiki terminal page. A non-terminal page can also be referenced this way, but it must append its ##.WebHome## part (e.g. ##doc:Sandbox.WebHome##).

160

*** **##wikiName##**: An optional string containing the name of a wiki. The link will point to a page inside that wiki. If no wiki is specified, the current wiki is used. Example: ##mywiki##.

161

*** **##spaceNameList##**: An optional dot-separated list of wiki Space names. If no space is specified the current space is used. Examples: ##Main##, ##A.B##, ##A.B.C##

162

*** **##documentName##**: A required string containing the name of the linked wiki page. Example: ##Welcome##

163

** **Wiki space**: A reference in the form **##space:[(wikiName):](spaceNameList)##**. Examples: ##space:Main##, ##space:mywiki:Main##, ##space:A.B.C##

164

*** **##space:##** A required string identifying the resource as an XWiki non-terminal page (i.e. a space).

165

*** **##wikiName##**: An optional string containing the name of a wiki. The link will point to a page inside that wiki. If no wiki is specified, the current wiki is used. Example: ##mywiki##

166

*** **##spaceNameList##**: A required list of dot-separated wiki Space names pointing to the final linked wiki Space (or non-terminal page). Examples: ##Main##, ##A.B##, ##A.B.C##

167

** **InterWiki page**: A reference in the form **##interwiki:[(interWikiAlias):](pageName)##**. Example: ##interwiki:wikipedia:XWiki##

168

*** **##interwiki:##** A required string identifying the resource as an InterWiki link.

169

*** **##interWikiAlias##**: An optional [[Inter Wiki>>https://en.wikipedia.org/wiki/InterWiki]] alias as defined in the InterWiki Map (see the [[Admin Guide>>https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/]]). Example: ##wikipedia##

170

*** **##pageName##**: A required string containing the name of the linked page. Example: ##XWiki##

171

** **Attachment**: A reference in the form **##attach~:~{~{~{(wikiName):}(spaceNameList).}(pageName)@}(imageName)##**

172

*** **##attach~:##** A required string identifying the reference as an XWiki Document attachment.

173

*** **##wikiName##**: An optional string containing the name of a wiki. The image reference will point to an image attached to a page inside that wiki. If no wiki is specified, the current wiki is used. Example: ##mywiki##.

174

*** **##spaceNameList##**: An optional dot-separated list of wiki Space names. If no space is specified the current space is used. Examples: ##Main##, ##A.B##, ##A.B.C##

175

*** **##pageName##**: An optional string containing the name of the wiki page to which the referenced image is attached. Example: ##Welcome##

176

*** **##attachmentName##**: Name of the attachment as it is stored in the wiki. Example: ##photo.png##

177

** **Page Attachment**: A reference in the form **##pageAttach~:~{~{~{(wikiName):}(pageNameList)/}(imageName)##**

178

*** **##pageAttach~:##** An required string identifying the reference as an XWiki Page attachment.

179

*** **##wikiName##**: An optional string containing the name of a wiki. The image reference will point to an image attached to a page inside that wiki. If no wiki is specified, the current wiki is used. Example: ##mywiki##.

180

*** **##pageNameList##**: An optional dot-separated list of wiki page names. If no page is specified the current page is used. Examples: ##Main##, ##A/B##, ##A/B/C##

181

*** **##attachmentName##**: Name of the attachment as it is stored in the wiki. Example: ##photo.png##

182

** **Email address**: A reference in the form **##mailto{{{:(}}}emailAddress)##** (###anchor## is not valid). Example: ##mailto~:john@smith.com##

183

*** **##mailto~:##** A required string identifying the resource as email.

184

*** **##emailAddress##**: Targeted email address. Example: ##john@smith.com##

185

** **Relative path**: A reference on the server in the form **##path{{{:(}}}relPath)##**. Example: ##path:$doc.getURL('reset')## produces target address ##http:~/~/server.domain.com/xwiki/bin/reset/Space/Page## where ##/xwiki/bin/reset/Space/Page## is produced by ##$doc.getURL('reset')##.

186

*** **##path:##** A required string identifying the resource as a relative path.

187

*** **##relPath##**: A required string containing the relative path of the resource on the server that shall be linked.

188

** **UNC (Windows Explorer)**: A reference in the form **##unc{{{:(}}}path)##**. The link is rendered as a ##file:~/~/## link. Examples: ##unc:C:\Windows\##, ##unc:~\~\myserver\path\img.png##, ##unc:home/user/somefile##

189

*** **##unc:##** A required string identifying the resource as a UNC (Windows Explorer) path.

190

*** **##path##**: A required string containing the local path of resource accessible by the user. Examples: ##C:\Windows\##, ##~\~\myserver\path\img.png##, ##home/user/somefile##

191

** **Untyped**: If none of the above-mentioned resource types are specified (i.e. no ##type:## resource prefix was specified in the link), then the link will be treated as a link to an XWiki terminal or non-terminal page using the following algorithm:

192

*** **##Terminal page##** in the current space, //only// if it exists. Example: ##~[~[A]]## is resolved to the equivalent of ##~[~[doc:currentSpace.A]]##

193

*** **##Non-terminal page##** in the current space. Example: ##~[~[A]]## is resolved to the equivalent of ##~[~[space:currentSpace.A]]##, which is the equivalent of ##~[~[doc:currentSpace.A.WebHome]]##

194

*** If the current page is non-terminal and the previous 2 checks above did not find an existing page, 2 additional checks are made:

195

**** **##Terminal page##** as sibling in the parent space, //only// if it exists. Example: The ##~[~[B]]## link inside the non-terminal page ##A.C## is resolved to the equivalent of ##~[~[doc:A.B]]##

196

**** **##Non-terminal page##** as sibling in the parent space, regardless if it exists or not. Example: The ##~[~[B]]## link inside the non-terminal page ##A.C## is resolved to the equivalent of ##~[~[space:A.B]]##, which is the equivalent of ##~[~[doc:A.B.WebHome]]##

197

*** //Note1 - Absolute links//: If the untyped link has 2 or more dot-separated components specified (i.e. that look like a space name and a page name), the above algorithm will resolve the page relative to the current wiki, and not the current space. Example: ##~[~[A.B]]## can be resolved to either ##~[~[doc:currentWiki:A.B]]## (if it exists) or to ##~[~[space:currentWiki:A.B]##] (equivalent of ##~[~[doc:currentWiki:A.B.WebHome]]##) and not to ##~[~[doc:currentWiki:currentSpace.A.B]]## or ##~[~[doc:currentWiki:currentSpace.A.B.WebHome]]##.

198

*** //Note2 - Special handling of ##.WebHome##//: If the untyped link ends in ##.WebHome##, it will //always// be handled as a terminal page. Example: ##~[~[A.WebHome]]## will always be resolved to the equivalent of ##~[~[doc:A.WebHome]]## and not to ##~[~[doc:A.WebHome.WebHome]]##.

199

* **##parameters##**: An optional list of space-separated parameters passed to the link. Example: ##queryString="mydata1=5&mydata2=Hello" anchor="HTableOfContents" target="~_blank"##

200

** **##queryString##**: An optional query string for specifying parameters that will be appended to the link target address and used in the rendered URL. Example: ##url:http:~/~/domain.com/path||queryString="mydata1=5&mydata2=Hello"## produces target address ##http:~/~/domain.com/path?mydata1=5&mydata2=Hello##

201

** **##anchor##**: An optional anchor name pointing to an anchor defined in the referenced link. Note that in XWiki anchors are automatically created for headings and images. Example: ##url:http:~/~/domain.com/path||anchor="HTableOfContents"## produces target address ##http:~/~/domain.com/path#HTableOfContents##

202

** **##target##**: An optional parameter that allows to open link target in new window. Example: ##target="~_blank"##

Wiki source code of XWikiSyntaxLinks

Navigation