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.

Here’s a typical wikilink, in each flavour:

Example 1
$ comrak -e wikilinks-title-after-pipe
See [[Home]], or [[how-to-use-comrak|How to use Comrak]].
Example 2
$ comrak -e wikilinks-title-before-pipe
See [[Home]], or [[How to use Comrak|how-to-use-comrak]].

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:

Example 3
$ comrak -e wikilinks-title-after-pipe
[[Home]] and [[https://example.org]]

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:

Example 4
$ comrak -e wikilinks-title-after-pipe
[[Home|Start here]]

With wikilinks-title-before-pipe, the title comes first:

Example 5
$ comrak -e wikilinks-title-before-pipe
[[Start here|Home]]

If both extensions are enabled, wikilinks-title-after-pipe takes precedence:

Example 6
$ comrak -e wikilinks-title-after-pipe -e wikilinks-title-before-pipe
[[Home|Start here]]

The rest of this document uses wikilinks-title-after-pipe, except where the order matters.

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:

Example 7
$ comrak -e wikilinks-title-after-pipe
[[ Home ]] and [[ Home | Start here ]]

A part may be empty:

Example 8
$ comrak -e wikilinks-title-after-pipe
[[]] and [[Home|]] and [[|Start here]]

A wikilink can’t have more than two parts. To use | in a part, escape it:

Example 9
$ comrak -e wikilinks-title-after-pipe
[[Home|Start|here]] and [[Home|Start\|here]]

Brackets must be escaped too. None of these are wikilinks, except the last:

Example 10
$ comrak -e wikilinks-title-after-pipe
[[Ho[me]] and [[Ho]me]] and [[Ho\[me\]]]

A wikilink may span lines, but not paragraphs:

Example 11
$ comrak -e wikilinks-title-after-pipe
[[Home|Start
here]]
Example 12
$ comrak -e wikilinks-title-after-pipe
[[Home

page]]

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:

Example 13
$ comrak -e wikilinks-title-after-pipe
[[Geschütztes Leerzeichen|Über  ]]
Example 14
$ comrak -e wikilinks-title-after-pipe
[[Name _of_ page|*Start* `here`]]

A line ending in a destination becomes a space. A line ending in a title stays as it is:

Example 15
$ comrak -e wikilinks-title-after-pipe
[[Home
page]]

Precedence

Comrak recognises a wikilink when inline parsing reaches its first [, so a code span that begins earlier takes precedence:

Example 16
$ comrak -e wikilinks-title-after-pipe
`[[Home]]`

A code span that would begin inside a wikilink doesn’t:

Example 17
$ comrak -e wikilinks-title-after-pipe
[[Ho`me]] and`

A wikilink takes precedence over a link beginning at the same bracket, and over a link reference definition with the same label:

Example 18
$ comrak -e wikilinks-title-after-pipe
[[Home]]/url
Example 19
$ comrak -e wikilinks-title-after-pipe
[[Home]]

[Home]: /url

A backslash escape before the first [ prevents a wikilink:

Example 20
$ comrak -e wikilinks-title-after-pipe
\[[Home]]

A wikilink may follow brackets that aren’t part of a link:

Example 21
$ comrak -e wikilinks-title-after-pipe
[see [[Home]] and [[[Home]]]

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:

Example 22
$ comrak -e wikilinks-title-after-pipe
[see [[Home]] here](/url)

An image description may contain a wikilink, as it may contain a link:

Example 23
$ comrak -e wikilinks-title-after-pipe
![see [[Home]] here](/url)

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:

Example 24
$ comrak -e wikilinks-title-after-pipe
![[photo.png]] and ![[photo.png|A photo]]

A backslash escape before the ! prevents an embed, but not the wikilink:

Example 25
$ comrak -e wikilinks-title-after-pipe
\![[photo.png]]

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:

Example 26
$ comrak -e wikilinks-title-after-pipe
[[javascript:alert(1)|Click me]]
Example 27
$ comrak -e wikilinks-title-after-pipe --unsafe
[[javascript:alert(1)|Click me]]

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 &amp;:

Example 28
$ comrak -e wikilinks-title-after-pipe
[[Home page]] and [[Ho\|me|Start\]here]] and [[R&amp;D]]

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 !:

Example 29
$ comrak -e wikilinks-title-after-pipe --sourcepos
[[Home|Start here]] and ![[photo.png]]

Interactions

--gfm doesn’t enable wikilinks:

Example 30
$ comrak --gfm
[[Home]]

With tables, a | in a table row separates cells, even inside a wikilink. Escape it to use two parts:

Example 31
$ comrak -e wikilinks-title-after-pipe -e table
| Page |
| ---- |
| [[Home\|Start here]] |
| [[Home|Start here]] |

With autolinks, a wikilink takes precedence over an autolink inside it:

Example 32
$ comrak -e wikilinks-title-after-pipe -e autolink
[[https://example.org]] and [[Home|www.example.org]]

With footnotes, a footnote reference has one [, so [[^1]] is a wikilink:

Example 33
$ comrak -e wikilinks-title-after-pipe -e footnotes
[[^1]] and [^1]

[^1]: A footnote.

With task lists, a wikilink at the start of a list item isn’t a task list item marker:

Example 34
$ comrak -e wikilinks-title-after-pipe -e tasklist
- [[x]] Home
- [x] [[Home]]

With --escaped-char-spans, backslash escapes in a title are rendered as they are elsewhere:

Example 35
$ comrak -e wikilinks-title-after-pipe --escaped-char-spans
[[Home|Start\|here]]

With --smart, a title’s punctuation stays as it is, since a title is plain text:

Example 36
$ comrak -e wikilinks-title-after-pipe --smart
[[Home|"Start" -- here]]

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:

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):

Example 37
$ comrak -e wikilinks-title-after-pipe
[[Home|Start\*here\*]]

Source positions of a title with entity references that spans lines (#908):

Example 38
$ comrak -e wikilinks-title-after-pipe --sourcepos
[[Home|St&auml;rt
&amp; here]]