Wikilinks vs Markdown Links: What Double Brackets Cost You in Portability

Wikilinks, the [[Page Name]] kind, are not part of Markdown. They are a wiki-engine convention that some tools add on top, and that is exactly why they cost you portability: a standard link means the same thing everywhere, while a double-bracket link means whatever the tool reading it decides.

What double brackets actually are

The syntax comes from wiki engines. In Python-Markdown, WikiLinks is an extension that you have to switch on by name. Once it is enabled, any bracketed word becomes a link, so this source:

See [[Meeting Notes]] for details.

turns into an anchor pointing at /Meeting_Notes/ with a wikilink CSS class. The spaces become underscores in the URL and stay as spaces in the label. That is one tool's rule, and the extension is in maintenance mode, so it will not grow new behavior.

Has Markdown ever tried to absorb the idea? Sort of. A CommonMark forum thread from 2014 proposed it as an extension, describing wiki links as shorthand for normal Markdown links. The thread records no formal decision, and a 2023 comment only suggested it "should at least be noted."

What standard Markdown links promise

The CommonMark spec defines inline links and link reference definitions. Both carry the destination in the file itself:

[Meeting Notes](meeting-notes.md)

[Meeting Notes][mn]

[mn]: meeting-notes.md

Whichever parser reads that, the target sits right there in the file. Nothing depends on a naming rule hidden inside an app. If you want the details of the two forms, our guide to inline and reference links covers when to use each.

Same brackets, different rules

Even among tools that accept double brackets, the rules disagree.

• Pipe order. In MediaWiki, [[a|b]] links to page a and shows b. GitLab wikis put the display text first and the slug after: [[How to use GitLab|how-to-use-gitlab]], and its docs say to use the slug, not the page name. Pandoc ships two separate extensions, wikilinks_title_after_pipe and wikilinks_title_before_pipe, to handle both orders.
• Name matching. MediaWiki treats spaces and underscores as equivalent and ignores case only for the first character, so [[atom]] reaches Atom but [[aTom]] does not.
• Anchors and special characters. MediaWiki section links such as [[Page name#Section name]] are case-sensitive, and the characters [ ] { } | must be percent-encoded.

So the same line of text can point at different files, or at nothing, depending on the tool. Your notes folder becomes a set of links that only one program fully understands. The risk grows with age: the longer a folder lives, the more links depend on a convention you may no longer remember, and the harder it is to tell a deliberate link from a stray pair of brackets.

What happens when a plain renderer meets a wikilink

Put a file containing [[Meeting Notes]] through a parser without the extension and you usually get the brackets back as literal text. Nothing errors. The link just isn't one. This is one more case of the same Markdown file rendering differently across parsers.

The second failure is slower, and nastier. Wikilinks resolve by name, so renaming a file in another tool, or moving it into a subfolder, can leave every [[...]] pointing at a page that no longer matches. A path-based link at least shows you the stale path, and a search for the old file name finds every place that needs fixing. A wikilink gives you only the name you typed, which may match nothing on disk.

Converting and living with wikilinks

Because a wikilink is shorthand for a relative link, conversion is mechanical once you know your tool's resolution rule. Confirm it first: does [[Meeting Notes]] mean Meeting Notes.md, meeting-notes.md, or a slug? Then rewrite:

Before: [[Meeting Notes]]
After:  [Meeting Notes](Meeting%20Notes.md)

A script or a careful find-and-replace with a checked mapping handles most folders. Spot-check aliases, which use the pipe, and anchors, which use the hash, by hand.

If you would rather keep them, limit the damage:

• Use exact file names as targets.
• Skip pipe aliases and section anchors.
• Write down which tool resolves them, so a later move stays a conversion job, not archaeology.

Wikilinks are still reasonable in a single-tool vault where speed of linking matters more than leaving. A plain-text Zettelkasten is a good example of linking ideas without a special app, and it works best when the links are ordinary ones.

How Carets fits in

Carets is a native notes and code editor for iPhone, iPad, and Mac, built around Markdown and plain text. Your notes stay as ordinary files organized into files, projects, and tags, so a standard link like [Meeting Notes](meeting-notes.md) stays readable in any editor, now or in ten years. Because the files are plain text, converting a folder of wikilinks later is a find-and-replace away, and syntax highlighting makes the brackets and paths easy to scan as you edit.

Download Carets on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Are wikilinks part of Markdown?

No. Core Markdown and the CommonMark spec define inline and reference links, not double-bracket links. Wikilinks come from wiki engines and are added by extensions or by the app you use.

What happens to a wikilink in a renderer without wikilink support?

It usually shows as literal text with the brackets, because the syntax has no meaning to a parser that has not enabled the extension.

How do I convert wikilinks to standard Markdown links?

Confirm how your current tool resolves a name to a file, then rewrite each wikilink as a relative link with the real file path. A script or a find-and-replace with a checked mapping is enough for most folders, with aliases and anchors checked by hand.

Can I keep wikilinks and stay portable?

Partly. Keep targets as exact file names, avoid pipe aliases and anchors, and note which tool resolves them, so a later conversion stays mechanical.