A wikilink is a link written the way wikis write them: a page name between double brackets, with an optional title to show in its place. Use wikilinks to link between the pages of a wiki or a collection of notes, where a page’s name is enough to find it.
Comrak’s wikilinks follow the wikilinks extensions of commonmark-hs, which Pandoc also uses. Those extensions come in two flavours, which differ in whether a wikilink’s title comes after its page name or before it. This document describes both, and Differences from commonmark-hs lists where Comrak parts ways. GitLab uses Comrak’s wikilinks, with the title before the page name, so this document is also the canonical spec for GitLab Flavored Markdown wikilinks.
To enable wikilinks with the title after the page name, pass -e wikilinks-title-after-pipe on the command line, or set extension.wikilinks_title_after_pipe in the options struct. For the title before the page name, pass -e wikilinks-title-before-pipe, or set extension.wikilinks_title_before_pipe.
<p>See <ahref="Home"data-wikilink="true">Home</a>, or <ahref="how-to-use-comrak"data-wikilink="true">How to use Comrak</a>.</p>
See [[Home]], or [[how-to-use-comrak|How to use Comrak]].
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">See </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve">, or </text><wikilinkdestination="how-to-use-comrak"embed="false"><textxml:space="preserve">How to use Comrak</text></wikilink><textxml:space="preserve">.</text></paragraph></document>
<p>See <ahref="Home"data-wikilink="true">Home</a>, or <ahref="how-to-use-comrak"data-wikilink="true">How to use Comrak</a>.</p>
See [[Home]], or [[How to use Comrak|how-to-use-comrak]].
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">See </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve">, or </text><wikilinkdestination="how-to-use-comrak"embed="false"><textxml:space="preserve">How to use Comrak</text></wikilink><textxml:space="preserve">.</text></paragraph></document>
Syntax
A wikilink is [[, followed by one or two wikilink parts, followed by ]]. Two parts are separated by |.
A wikilink has a destination, which is the page name or URL it links to, and a title, which is the text it shows. A wikilink with one part uses that part as both:
<p><ahref="Home"data-wikilink="true">Home</a> and <ahref="https://example.org"data-wikilink="true">https://example.org</a></p>
[[Home]] and [[https://example.org]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve"> and </text><wikilinkdestination="https://example.org"embed="false"><textxml:space="preserve">https://example.org</text></wikilink></paragraph></document>
Title order
A wikilink with two parts uses one as its destination and the other as its title. With wikilinks-title-after-pipe, the destination comes first:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start here</text></wikilink></paragraph></document>
With wikilinks-title-before-pipe, the title comes first:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start here</text></wikilink></paragraph></document>
If both extensions are enabled, wikilinks-title-after-pipe takes precedence:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start here</text></wikilink></paragraph></document>
The rest of this document uses wikilinks-title-after-pipe, except where the order matters.
Wikilink parts
A wikilink part is a sequence of characters other than [, ], and |, at most 1,000 bytes long. A backslash escape may include any of those three characters in a part. Spaces and tabs at either end of a part are ignored:
<p><ahref="Home"data-wikilink="true">Home</a> and <ahref="Home"data-wikilink="true">Start here</a></p>
[[Home]] and [[Home|Start here]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve"> and </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start here</text></wikilink></paragraph></document>
<p><ahref=""data-wikilink="true"></a> and <ahref="Home"data-wikilink="true"></a> and <ahref=""data-wikilink="true">Start here</a></p>
[[|]] and [[Home|]] and [[|Start here]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination=""embed="false"/><textxml:space="preserve"> and </text><wikilinkdestination="Home"embed="false"/><textxml:space="preserve"> and </text><wikilinkdestination=""embed="false"><textxml:space="preserve">Start here</text></wikilink></paragraph></document>
A wikilink can’t have more than two parts. To use | in a part, escape it:
<p>[[Home|Start|here]] and <ahref="Home"data-wikilink="true">Start|here</a></p>
\[\[Home|Start|here\]\] and [[Home|Start\|here]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[[Home|Start|here]] and </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start|here</text></wikilink></paragraph></document>
Brackets must be escaped too. None of these are wikilinks, except the last:
<p>[[Ho[me]] and [[Ho]me]] and <ahref="Ho%5Bme%5D"data-wikilink="true">Ho[me]</a></p>
\[\[Ho\[me\]\] and \[\[Ho\]me\]\] and [[Ho\[me\]]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[[Ho[me]] and [[Ho]me]] and </text><wikilinkdestination="Ho[me]"embed="false"><textxml:space="preserve">Ho[me]</text></wikilink></paragraph></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start
here</text></wikilink></paragraph></document>
$ comrak -e wikilinks-title-after-pipe -t commonmark -t xml
[[Home
page]]
[[Home
page]]
<p>[[Home</p><p>page]]</p>
\[\[Home
page\]\]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[[Home</text></paragraph><paragraph><textxml:space="preserve">page]]</text></paragraph></document>
Destinations and titles
A wikilink’s destination and title are both plain text. Backslash escapes and entity references are interpreted in both, but no other inline syntax is:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Geschütztes Leerzeichen"embed="false"><textxml:space="preserve">Über &nbsp;</text></wikilink></paragraph></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home page"embed="false"><textxml:space="preserve">Home
page</text></wikilink></paragraph></document>
Precedence
Comrak recognises a wikilink when inline parsing reaches its first [, so a code span that begins earlier takes precedence:
$ comrak -e wikilinks-title-after-pipe -t commonmark -t xml
`[[Home]]`
[[Home]]
<p><code>[[Home]]</code></p>
`[[Home]]`
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><codexml:space="preserve">[[Home]]</code></paragraph></document>
A code span that would begin inside a wikilink doesn’t:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Ho`me"embed="false"><textxml:space="preserve">Ho`me</text></wikilink><textxml:space="preserve"> and`</text></paragraph></document>
A wikilink takes precedence over a link beginning at the same bracket, and over a link reference definition with the same label:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve">(/url)</text></paragraph></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink></paragraph></document>
A backslash escape before the first [ prevents a wikilink:
$ comrak -e wikilinks-title-after-pipe -t commonmark -t xml
\[[Home]]
[[Home]]
<p>[[Home]]</p>
\[\[Home\]\]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[[Home]]</text></paragraph></document>
A wikilink may follow brackets that aren’t part of a link:
<p>[see <ahref="Home"data-wikilink="true">Home</a> and [<ahref="Home"data-wikilink="true">Home</a>]</p>
\[see [[Home]] and \[[[Home]]\]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[see </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve"> and [</text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve">]</text></paragraph></document>
Links can’t contain other links. A wikilink is a link, so once Comrak recognises one, the brackets before it can’t form a link:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[see </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve"> here](/url)</text></paragraph></document>
An image description may contain a wikilink, as it may contain a link:
$ comrak -e wikilinks-title-after-pipe -t commonmark -t xml
![see [[Home]] here](/url)
<p><imgsrc="/url"alt="see Home here" /></p>
![see [[Home]] here](/url)
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><imagedestination="/url"title=""><textxml:space="preserve">see </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink><textxml:space="preserve"> here</text></image></paragraph></document>
Embeds
A wikilink directly after ! is an embed. An embed is meant to show the content it links to, such as an image or another page, in place. What can be embedded, and how, is up to whatever consumes Comrak’s output, so HTML output renders an embed as an ordinary wikilink:
<p><ahref="photo.png"data-wikilink="true">photo.png</a> and <ahref="photo.png"data-wikilink="true">A photo</a></p>
![[photo.png]] and ![[photo.png|A photo]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="photo.png"embed="true"><textxml:space="preserve">photo.png</text></wikilink><textxml:space="preserve"> and </text><wikilinkdestination="photo.png"embed="true"><textxml:space="preserve">A photo</text></wikilink></paragraph></document>
A backslash escape before the ! prevents an embed, but not the wikilink:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">!</text><wikilinkdestination="photo.png"embed="false"><textxml:space="preserve">photo.png</text></wikilink></paragraph></document>
With extension.wikilinks_ignore_embeds, Comrak doesn’t recognise embeds. ![ begins an image as it does in CommonMark, and the brackets after it can’t form a wikilink. The option has no command-line flag yet.
Output
HTML output renders a wikilink as an <a> element with the attribute data-wikilink="true". Its href attribute is the destination, percent-encoded, and its content is the title.
As with links, Comrak removes destinations that could run script, such as those beginning with javascript:, unless --unsafe is given:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="javascript:alert(1)"embed="false"><textxml:space="preserve">Click me</text></wikilink></paragraph></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="javascript:alert(1)"embed="false"><textxml:space="preserve">Click me</text></wikilink></paragraph></document>
CommonMark output writes a wikilink with one part if its title is the same as its destination, and with two parts in the enabled order otherwise. It escapes \, [, ], and | in each part with a backslash, and writes a & that could begin an entity reference as &:
<p><ahref="Home%20page"data-wikilink="true">Home page</a> and <ahref="Ho%7Cme"data-wikilink="true">Start]here</a> and <ahref="R&D"data-wikilink="true">R&D</a></p>
[[Home page]] and [[Ho\|me|Start\]here]] and [[R&D]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home page"embed="false"><textxml:space="preserve">Home page</text></wikilink><textxml:space="preserve"> and </text><wikilinkdestination="Ho|me"embed="false"><textxml:space="preserve">Start]here</text></wikilink><textxml:space="preserve"> and </text><wikilinkdestination="R&D"embed="false"><textxml:space="preserve">R&D</text></wikilink></paragraph></document>
In XML output, a wikilink is a wikilink element with a destination attribute, and an embed attribute that’s true for an embed and false otherwise.
In the AST, a wikilink is a NodeValue::WikiLink. Its NodeWikiLink holds the destination (url), and whether it’s an embed (embed), with the title as its children.
A wikilink’s source position covers its brackets, including an embed’s !:
<pdata-sourcepos="1:1-1:38"><adata-sourcepos="1:1-1:19"href="Home"data-wikilink="true">Start here</a> and <adata-sourcepos="1:25-1:38"href="photo.png"data-wikilink="true">photo.png</a></p>
[[Home|Start here]] and ![[photo.png]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentsourcepos="1:1-1:38"xmlns="http://commonmark.org/xml/1.0"><paragraphsourcepos="1:1-1:38"><wikilinksourcepos="1:1-1:19"destination="Home"embed="false"><textsourcepos="1:8-1:17"xml:space="preserve">Start here</text></wikilink><textsourcepos="1:20-1:24"xml:space="preserve"> and </text><wikilinksourcepos="1:25-1:38"destination="photo.png"embed="true"><textsourcepos="1:28-1:36"xml:space="preserve">photo.png</text></wikilink></paragraph></document>
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><textxml:space="preserve">[[Home]]</text></paragraph></document>
With tables, a | in a table row separates cells, even inside a wikilink. Escape it to use two parts:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><table><table_header><table_cell><textxml:space="preserve">Page</text></table_cell></table_header><table_row><table_cell><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start here</text></wikilink></table_cell></table_row><table_row><table_cell><textxml:space="preserve">[[Home</text></table_cell></table_row></table></document>
With autolinks, a wikilink takes precedence over an autolink inside it:
<p><ahref="https://example.org"data-wikilink="true">https://example.org</a> and <ahref="Home"data-wikilink="true">www.example.org</a></p>
[[https://example.org]] and [[Home|www.example.org]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="https://example.org"embed="false"><textxml:space="preserve">https://example.org</text></wikilink><textxml:space="preserve"> and </text><wikilinkdestination="Home"embed="false"><textxml:space="preserve">www.example.org</text></wikilink></paragraph></document>
With footnotes, a footnote reference has one [, so [[^1]] is a wikilink:
<p><ahref="%5E1"data-wikilink="true">^1</a> and <supclass="footnote-ref"><ahref="#fn-1"id="fnref-1"data-footnote-ref>1</a></sup></p><sectionclass="footnotes"data-footnotes><ol><liid="fn-1"><p>A footnote. <ahref="#fnref-1"class="footnote-backref"data-footnote-backrefdata-footnote-backref-idx="1"aria-label="Back to reference 1">↩</a></p></li></ol></section>
[[^1]] and [^1]
[^1]:
A footnote.
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="^1"embed="false"><textxml:space="preserve">^1</text></wikilink><textxml:space="preserve"> and </text><footnote_referencelabel="1"/></paragraph><footnote_definitionlabel="1"><paragraph><textxml:space="preserve">A footnote.</text></paragraph></footnote_definition></document>
With task lists, a wikilink at the start of a list item isn’t a task list item marker:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><listtype="bullet"tasklist="true"tight="true"><item><paragraph><wikilinkdestination="x"embed="false"><textxml:space="preserve">x</text></wikilink><textxml:space="preserve"> Home</text></paragraph></item><taskitemcompleted="true"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Home</text></wikilink></paragraph></taskitem></list></document>
With --escaped-char-spans, backslash escapes in a title are rendered as they are elsewhere:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start</text><escaped><textxml:space="preserve">|</text></escaped><textxml:space="preserve">here</text></wikilink></paragraph></document>
With --smart, a title’s punctuation stays as it is, since a title is plain text:
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">"Start" -- here</text></wikilink></paragraph></document>
Differences from commonmark-hs
Pandoc uses commonmark-hs’s wikilinks extensions, so the comparison here is with Pandoc 3.7. Its other extensions and options differ from Comrak’s, so the examples under Interactions, and those with source positions, aren’t comparable. On every other example above, Pandoc and Comrak agree on HTML output, except that Pandoc:
splits a wikilink at its first |, so a title may contain | (example 9);
keeps a line ending in a destination as it is (example 15);
keeps a link that contains a wikilink, and renders the wikilink as a <span> element instead (example 22);
has no embeds, so a ! before a wikilink is literal text (example 24); and,
doesn’t remove destinations that could run script (example 26).
Pandoc also has no limit on a part’s length. Its HTML output gives a wikilink the class wikilink, rather than a data-wikilink attribute, and doesn’t percent-encode the destination.
Regressions
The following examples guard against regressions.
A title with backslash escapes is a single text node (#575):
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentxmlns="http://commonmark.org/xml/1.0"><paragraph><wikilinkdestination="Home"embed="false"><textxml:space="preserve">Start*here*</text></wikilink></paragraph></document>
Source positions of a title with entity references that spans lines (#908):
<pdata-sourcepos="1:1-2:12"><adata-sourcepos="1:1-2:12"href="Home"data-wikilink="true">Stärt
& here</a></p>
[[Home|Stärt & here]]
<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEdocument SYSTEM "CommonMark.dtd"><documentsourcepos="1:1-2:12"xmlns="http://commonmark.org/xml/1.0"><paragraphsourcepos="1:1-2:12"><wikilinksourcepos="1:1-2:12"destination="Home"embed="false"><textsourcepos="1:8-2:10"xml:space="preserve">Stärt
& here</text></wikilink></paragraph></document>