Write the Link Once, Read It Anywhere: Use `[Text](URL)` So Your Notes Survive the App

Write the inline link as [text](url) — six characters of bracket and parenthesis around the words you want clickable and the address they point at. That is the one link form the Markdown specification defines, and every conformant reader on earth turns it into a real <a> tag. App-specific shapes silently become literal text the moment you leave the tool.

This is the positive companion to a piece we already wrote about why [[wikilinks]] aren't plain Markdown. That essay names the trap. This one is the way out: the grammar, a five-minute portability test you can paste into a terminal, the steps to convert what you have, and the three failure modes worth knowing before they bite. Markdown was created by John Gruber in 2004 and standardized in 2014 by the CommonMark working group around John MacFarlane;¹ the inline link is the part of that standard with the least ambiguity, and the most leverage.

The single rule — six characters around the link

Write [text](url). The bracketed text is what the reader sees and clicks; the URL in parentheses is where the click goes. That is the entire inline-link grammar. CommonMark §6.3 defines it once: "An inline link consists of a link text followed immediately by a left parenthesis (, an optional link destination, an optional link title, and a right parenthesis )."²

The same section opens with a sentence that closes the door on every other form: "There are two basic kinds of links in Markdown. In inline links the destination and title are given immediately after the link text. In reference links the destination and title are defined elsewhere in the document."³ Two forms. Both portable. [[ ]] is not one of them — the word "wikilink" appears zero times in the CommonMark spec, and zero times in the GitHub Flavored Markdown spec, whose four named extensions are exactly Tables, Task list items, Strikethrough, and Autolinks.⁴ The thing your app may parse for convenience is, in standards terms, not a thing.

The second portable form, reference links, is worth knowing as the long-document cousin. You write [the docs][docs] in the body and define [docs]: https://example.com once at the bottom of the file; the renderer joins them by the bracketed label. Same grammar family, same universal support, useful when the same URL appears five times in one essay. GitHub's own writing docs phrase the inline shape the way every other reader does: "You can create an inline link by wrapping link text in brackets [ ], and then wrapping the URL in parentheses ( )."⁵ One construction, one meaning, every reader.

The five-minute portability test — paste this into a terminal

The cheapest way to see what travels is to send both forms to a renderer that follows the spec and watch what comes back. GitHub's Markdown REST API does exactly this, in two curl commands. Run them and the question is settled. The portable form returns a real anchor tag; the wikilink form returns the brackets, unchanged.

# The portable form → a real <a> tag
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"text":"See [the docs](https://example.com) for details.","mode":"markdown"}' \
  https://api.github.com/markdown
# → <p>See <a href="https://example.com" rel="nofollow">the docs</a> for details.</p>

# The wikilink form → literal text, no link
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"text":"See [[my note]] for details.","mode":"markdown"}' \
  https://api.github.com/markdown
# → <p>See [[my note]] for details.</p>

This is the same answer you would get from any CommonMark-conformant renderer — Pandoc, the major static-site generators, and the editors built on the open Markdown parsers. GitHub is the largest such surface, which makes it the most instructive: the world's biggest Markdown audience reads only what the spec defines. The bracketed name in the second receipt is not a "broken link" the way a 404 is broken. It is text. The renderer never tried to make a link of it, because no specification told it to.

Pandoc — the universal document converter that translates between sixty-plus formats — phrases the same inline-link rule in its own user guide, almost word for word: "An inline link consists of the link text in square brackets, followed by the URL in parentheses. (Optionally, the URL can be followed by a link title, in quotes.)"⁶ When the spec, GitHub's renderer, and the universal converter all describe the same grammar in the same words, "every Markdown reader on earth agrees" stops being a slogan and starts being a property of the file. Wikilinks are an extension you opt into; Pandoc supports them only when you pass +wikilinks_title_after_pipe on the command line.⁷ No flag, no link.

How to convert [[wikilinks]] to [text](url) — three concrete steps

Most apps that default to wikilinks ship the off-ramp themselves — the vendor named the seam and handed you the switch. Obsidian's own help says it plainly: "By default, due to its more compact format, Obsidian generates links using the Wikilink format. If interoperability is important to you, you can disable Wikilinks and use Markdown links instead."⁸

1. Flip the default to Markdown links. In Obsidian: Settings → Files and links → toggle Use Wikilinks off. Other tools have an equivalent — Logseq, Bear, and Notion-style outliners all ship a "link format" preference because the demand for interoperability is steady.⁸ Once it is off, every new link you write is portable by default; you only need to mop up the old ones.
2. Convert the existing [[ ]] links in place. For a vault you can open in a terminal, a Pandoc one-liner is the most surgical pass: pandoc --from=markdown+wikilinks_title_after_pipe --to=commonmark input.md -o output.md turns [[URL|title]] into [title](URL) against the CommonMark output target.⁷ Apps with a "convert wikilinks" command do the same work without the shell; either way, do one folder at a time and check a sample by hand.
3. Verify with the receipt above. Pick three converted notes at random. Render them through any spec-conformant tool that is not the app you wrote them in. If the link is a link, the conversion took. If the bracketed name is still text, the conversion is partial — usually a stray block reference or an aliased pipe form the converter didn't catch.

This is also where the honest tradeoff lands. Wikilinks were faster to type because they auto-completed against your note titles and let you skip the path entirely; the portable form is two characters longer and asks you to think about where the target lives. That is a real cost paid up front to remove a real risk paid later, and it is the entire point.

Three failure modes worth knowing — what also won't travel

Wikilinks are the famous trap, but they are not the only one. A note vault accumulates link shapes the way a coastline accumulates plastic. Three are worth naming because they look like links inside one app and become inert text outside it; the right time to find them is now, not at migration.

• Block references. The ^block-id and #^abc123 forms — links that point at a specific paragraph or block within a file — are a vendor convention, not a spec feature. Obsidian's own documentation is explicit: "Block references are specific to Obsidian and not part of the standard Markdown format."⁹ Treat any deep link into a sub-paragraph as app-specific until you have confirmed otherwise. The same applies to the embed shape that prefixes a wikilink with a bang (the ![[note#^block]] form), which sits one notch above the plain link as a transclusion — a different problem, equally non-portable.
• Custom URI schemes. Links written as obsidian://, logseq://, bear://, notion://, and friends open the right place inside the app that registered the scheme — and a dead protocol handler in every other context. They are useful as bookmarks inside a workflow. They are not useful as the durable internal links between your notes. Prefer plain relative paths or https:// URLs for anything you might still want to follow ten years from now.
• Vault-relative shorthand. Even a [text](path) link can break if the path is shorthand the app fills in for you — a name-only target ([My Note](My Note)) that the app resolves against an index, with no actual .md extension on disk. The grammar is spec-legal; the resolution is app-specific. Write the path the way a stranger would have to: include the extension, include the folder where helpful, encode spaces as %20.

The trade across all three is the same as the wikilink trade. Each was added because it was friendlier inside one product. Each becomes literal text the moment that product is not in the loop. If a link matters, write it in the shape the specification defines and accept the keystrokes.

The honest caveats — what "survives the app" does not mean

"Survives the app" is not the same as "survives forever," and a tutorial that hides the distinction is selling you a dream that no link form can deliver. Four caveats are worth keeping near the keyboard. They keep the win narrow, honest, and real.

• The link form survives; the destination URL still rots. A clean [text](url) link will render as an anchor tag a decade from now in any spec-conformant reader. Whether that anchor resolves to the page you meant is a separate question — link rot is the live web's failure mode, not Markdown's. We covered that elsewhere: save the page, not the link, because external URLs vanish on a schedule no syntax can fix.
• Spaces, paths, and titles still vary across renderers. Spaces in a path need URL-encoding (%20) for many readers; relative paths resolve differently depending on whether the renderer treats your notes as files or as URLs; some renderers strip the optional link title in quotes and some preserve it. The grammar is universal; the resolution of that grammar still depends on the tool.
• Wikilinks are not evil — they are app-specific. Inside a single vault you intend to keep in one tool for the long haul, [[ ]] is genuinely faster to type, auto-completes, and gets repaired by the tool on rename. The choice is speed-now versus portability-later, not right versus wrong. The paired essay walks that tradeoff at length.
• A portable link is not the same as a findable target. Once the link is [text](path) instead of an autocompleting [[ ]], you need a way to find the target you intend to point at. That is what searching across plain files is for — and searching beats organizing once the corpus is more than a few hundred notes.

The point of the rule is not perfection. It is a floor under the rest of the promise. A note written in plain Markdown is portable; a connection between two such notes is portable only when its grammar is the one the standard defines.¹⁰ Hold the floor, and everything else gets to be a choice.

How this works in MNMNOTE

MNMNOTE writes CommonMark inline links. The .md files on your device contain [text](url) exactly as the spec defines, so the same files open — and the same links resolve — in any other Markdown reader you choose next. Publish those notes as a static site and Jekyll, Hugo, and MkDocs pick the links up natively, no plugin required.

FAQ

What's the difference between [text](url) and [[wikilinks]]?

[text](url) is the inline link defined by the CommonMark specification — a link text in square brackets followed by a URL in parentheses — and every conformant Markdown reader renders it as a real hyperlink.² [[wikilinks]] are an app-specific convention; the word "wikilink" appears nowhere in the CommonMark spec or in GitHub Flavored Markdown's four extensions,⁴ so a strict renderer prints the brackets as literal text.

Will my note links break if I change apps?

The links written as [text](url) will not — that exact form is in the standard and renders the same in every CommonMark-conformant reader.² Links written as [[ ]], block references like ^block-id, or custom URI schemes like obsidian:// will break, because each is parsed only by the app that defined it. Convert the app-specific shapes before you move; leave the portable ones alone.

How do I link between notes in Markdown?

Write the link as [text](path-or-url) — the text in square brackets, the destination in parentheses, no space between them. GitHub's own writing docs put it the same way: "You can create an inline link by wrapping link text in brackets [ ], and then wrapping the URL in parentheses ( )."⁵ For a link between two notes in the same folder, the path is the target's filename ([The other note](other-note.md)), with spaces encoded as %20.

How do I convert [[wikilinks]] to Markdown links?

Flip the app default first — Obsidian's Use Wikilinks toggle is in Settings → Files and links, and the vendor's own help recommends turning it off "if interoperability is important to you."⁸ For the existing links, run a converter pass: a Pandoc one-liner using the wikilinks_title_after_pipe extension is the most surgical, and most note apps that default to wikilinks ship a built-in "convert links" command for the same job.⁷

Why did my links break when I renamed a note?

Because keeping a link valid after a rename is an app feature, not a property of the files. Inside a tool that watches every reference to a note's path, the link survives the rename; outside that tool, no syntax repairs itself. This is true for [[wikilinks]] and for [text](path) alike — one Obsidian forum user named the pain exactly: "stopped doing this because renaming a note led to a broken link."¹¹ The fix is the same either way: use the portable grammar, and accept that rename-tracking is something an app does for you while you are using it.

Are Markdown links the same across apps?

The [text](url) form is, as long as the reader follows CommonMark or builds on a parser that does — that includes Pandoc (whose own user guide phrases the grammar identically: "An inline link consists of the link text in square brackets, followed by the URL in parentheses"),⁶ GitHub's renderer, the major static-site generators, and most modern editors. Resolution of relative paths and handling of the optional title can vary, but the link itself is universally recognized as a link.

The text in your notes is portable because Markdown is a format, not a product; the links between those notes are portable only when they share the same property.

Plain notes in plain Markdown on your own device, linked the way the specification defines, open in any reader you choose next — that is the standard worth holding any tool to, including mnmnote.com.