The Links Between Your Notes Aren't Plain Markdown

Your notes are plain Markdown, so you can leave any app whenever you want. That promise is true for the text and quietly false for the connections. The [[wikilinks]] joining your notes are not part of the Markdown standard — they are an app convention. Move to a tool that reads them differently, and the links can break.

This is the seam most people miss. Markdown won because it is a format, not a product: a .md file opens the same in any editor on any machine. But "the links between my notes are Markdown too" is an assumption, not a fact. The connective tissue of a vault — the thing that turns a folder of files into a second brain — often lives in a syntax no specification ever defined. It works perfectly until the day you switch.

The point here is not that wikilinks are bad. They are compact, they auto-complete, and a good app keeps them tidy when you rename. The point is narrower and more useful: know which of your syntax is standard and which is app-specific, because only one of those is guaranteed to travel.

Are wikilinks part of the Markdown standard?

No. The two reference standards — CommonMark and GitHub Flavored Markdown — define a fixed set of features, and [[ ]] wikilinks are in neither. CommonMark states plainly that "there are two basic kinds of links in Markdown," inline and reference, and double brackets are not a third.¹ Anything beyond the spec is a feature your app added, not the format.

There are two formal Markdown standards worth knowing by name. CommonMark is the precise, unambiguous specification most modern tools follow.¹ GitHub Flavored Markdown builds on CommonMark and adds exactly four named extensions: Tables, Task list items, Strikethrough, and Autolinks.² That is the complete public list. Wikilinks appear in neither document.

The consequence is subtle. A wikilink is not "Markdown with a typo." It is a perfectly valid string that the standard simply ignores. So whether [[My Note]] becomes a link depends entirely on the app you happen to be in. Inside an app that parses it, it resolves. Inside a strict renderer, it is just five characters and a name. The format never promised you anything about it.

What actually happens to a wikilink when you leave the app?

It degrades to literal text. A renderer that follows the standard does not error and does not warn — it simply prints the brackets. You can watch this happen: paste [[ ]] syntax into any tool that renders pure CommonMark or GFM, and the link arrives as plain characters with nothing behind them.

CommonMark documents this behavior directly. Its Example 590 feeds ![[foo]] into a compliant parser, and the output is <p>![[foo]]</p>: the double brackets pass straight through as text, because the spec has no rule that turns them into a link.¹ The standard is not failing here. It is doing exactly what it says: an undefined construct is left alone.

You can reproduce the same result against the largest Markdown renderer on the internet. Send a wikilink to GitHub's own Markdown API and it comes back inert:

INPUT:   See [[My Note]] for details.
OUTPUT:  <p>See [[My Note]] for details.</p>

GitHub renders the sentence as plain prose; the bracketed name is text, not a link.³ (GitHub wikis are a separate product with their own wiki syntax, which is not the same as your .md files rendering on GitHub.) Multiply that one broken link by a few thousand notes, and "I can leave anytime" starts to feel less like a guarantee and more like a hope.

Why do links break when you just rename a note?

Because keeping a link valid after a rename is an app feature, not a property of your files. When a note's title changes, its link target changes too, and something has to rewrite every reference to it. If your app does that for you, the link survives. If it doesn't, the link points at a name that no longer exists.

Obsidian's documentation names the mechanism exactly: "Obsidian can automatically update internal links in your vault when you rename a file."⁴ Read that carefully. The durability of your connections is a setting inside the app — a service the tool performs, not something baked into the Markdown on disk. The files do not heal themselves; the app heals them while you are inside it.

This is where the honest caveat matters, and it cuts against the easy moral. Standard Markdown links, the [text](relative-path.md) form, are not immune to this. Rename the target file and a standard link breaks just as surely, unless the app you are in updates it for you. The lesson is not "wikilinks break, standard links are immortal."

The lesson is that the survival of your connections, in any syntax, depends on the tool managing them — and once you leave that tool, no tool is managing them at all. Real people hit this wall: one Obsidian forum user described doing exactly the right thing and then "stopped doing this because renaming a note led to a broken link."⁵

So which links actually survive a move, and how do I keep mine portable?

Standard inline links survive best, because they are the one link form the specification guarantees. Writing a connection as [Three laws of motion](Three laws of motion.md) means any compliant Markdown tool will at least recognize it as a link with a path, even if it can no longer resolve where that path points. Wikilinks and block references make no such promise.

The fix lives inside the apps themselves, which is the most honest evidence that this is a real tradeoff and not a manufactured one. Obsidian writes wikilinks by default "due to its more compact format," then offers the off-ramp in the same breath: "If interoperability is important to you, you can disable Wikilinks and use Markdown links instead."⁶ The same toggle changes [[Three laws of motion]] into [Three laws of motion](Three%20laws%20of%20motion).⁷ The vendor is not hiding the seam. It is handing you the switch.

Some link types travel worse than others, and again the clearest warning comes from the tool that makes them. Block references, the ^block-id links that point at a single paragraph, are flagged by Obsidian's own docs: "Block references are specific to Obsidian and not part of the standard Markdown format. Links containing block references won't work outside of Obsidian."⁸ That is a vendor telling you, in writing, which of your links are non-portable. It is worth taking literally.

So the practical rule is short. If you might ever move — and over a long enough timeline, you will — prefer standard relative-path links for the connections you cannot afford to lose. Accept that they are uglier and that they too need an app to keep them valid on rename. The trade you are making is clarity for compactness, and durability for convenience.

When are wikilinks the right choice anyway?

When you are not planning to leave. Wikilinks earn their keep inside a single, stable app: faster to type, auto-completing from your note titles, supporting aliases, and repaired on rename by a capable tool. For a vault that lives its whole life in one tool, that convenience is real and the portability question never comes due.

The decision is not moral, it is situational. A researcher building a five-year vault they intend to keep in one app should use whatever is fastest to write, and that is often the wikilink. Someone who has already migrated once — or who treats their notes as a thirty-year archive that will outlive several apps — should weigh portability more heavily. They are the person who will eventually paste a folder into a new tool and watch the connections go quiet.

What you should not do is choose by default and assume the connections are as portable as the prose. They are not. The text is the format's promise; the links are the app's. Decide which one you are trusting, on purpose, before the move forces the answer.

The deeper principle: own the connections, not just the files

Plain text is durable because it is owned, and ownership has to reach past the words on the page to the relationships between them. Steph Ango, who leads Obsidian, put the durability case best: "Apps are ephemeral, but your files have a chance to last."⁹ The corollary is easy to skip: your links are part of your files, and they only last in a form that lasts.

Ango's own framing is "file over app": "if you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read."⁹ A wikilink fails the second half of that test through no fault of the philosophy. It is easy to write and hard to retrieve anywhere outside the app that understands it. The connection is a real artifact you made, and an artifact written in a private dialect is only half-owned.

This is why "my notes are plain files" deserves one more question: plain files, yes, but are the paths between them plain too? A note app that stores everything as plain Markdown on your own device, with connections in the standard relative-path form, keeps that promise all the way down. The text and the links both open in any editor, after the app is gone. That property is worth checking for in any tool before you decide your notes are truly yours.

It also reframes a sibling trap. A graph view full of backlinks looks like a web of durable knowledge, but a backlink records that two notes touch, not why — and if the link itself is non-portable, even that much can vanish in a move. Portability is the floor beneath every other note-taking promise. The text, the images you attach, and the links between them all have to clear it.

FAQ

Are wikilinks portable to other Markdown apps?

Partially, and unreliably. Many apps and plugins parse [[ ]], but it is not in the CommonMark or GitHub Flavored Markdown standard, so support is per-app and inconsistent. Different tools resolve the same name differently, some require a file extension, and a strict renderer drops the link to literal text entirely.¹³

Wikilink vs Markdown link — which should I use?

Use Markdown links if you value interoperability; use wikilinks if you value compactness inside one app. That is the vendor's own answer: Obsidian defaults to wikilinks "due to its more compact format" but says to "disable Wikilinks and use Markdown links instead" if "interoperability is important to you."⁶⁷

Why did my links break when I renamed or moved a note?

Because keeping links valid on rename is an app feature, not a file property. Obsidian, for example, "can automatically update internal links in your vault when you rename a file" — but only while you are using it.⁴ No syntax, standard or otherwise, repairs itself once you leave the tool that was maintaining it.

Do [[wikilinks]] work on GitHub or in a static site generator?

Not in a plain .md file. GitHub's own Markdown renderer turns See [[My Note]] for details. into the literal text See [[My Note]] for details., with no link behind it.³ GitHub wikis are a separate product with their own syntax; that is not the same as your repository's Markdown files.

Are block references and heading links portable?

Block references are not. Obsidian's documentation states that "block references are specific to Obsidian and not part of the standard Markdown format" and that "links containing block references won't work outside of Obsidian."⁸ Treat any deep link into a paragraph or heading as app-specific until you have confirmed otherwise.

Should I disable wikilinks in my note app?

Only if portability outranks convenience for you. The standard [text](relative-path.md) form travels better but is uglier to write and still breaks on rename unless the app updates it. If your vault will spend its whole life in one tool, the compact wikilink is a reasonable default. If you expect to migrate, prefer the portable form on purpose.

The format you can read anywhere is only as portable as the syntax you wrote it in.

If your notes live as plain Markdown on your own device, the same should be true of the links between them — the connections, not just the words, are what you actually own. That is the standard worth holding any tool to, including mnmnote.com.