Wikilinks and backlinks in Markdown notes

Managing notes6 min read

A wikilink is a link written as a note's title inside double square brackets, like [[Project plan]]. In MiaoYan, typing one links to the note whose file name exactly matches that title, and the linked note lists incoming references as backlinks. They keep links short and readable. The trade-off is that wikilinks are not part of standard Markdown. In MiaoYan, they match titles only, so renaming a note breaks existing links, and aliases or heading links are not supported.

A standard Markdown link carries a text label and a destination: [Project plan](Projects/Project%20plan.md). The destination is a path, so it breaks when you move the file, and spaces have to be URL encoded. Every Markdown renderer understands it.

A wikilink drops the path and the label: [[Project plan]]. You name the note and the app finds it. Obsidian, which popularized the style, describes the same split in its documentation: wikilinks use double brackets and are generated by default because they are more compact, while Markdown links need URL encoding and can be switched on by disabling "Use [[Wikilinks]]".

Normal Markdown link Wikilink
Syntax [text](path.md) [[Note title]]
Points to A path A title
Works in any Markdown viewer Yes No, the app must support it
Survives moving the file No, the path changes Yes, if the title stays
Survives renaming the file Only if the path is updated No, the title changes
Custom link text [text](...) Not in MiaoYan

Portability is the real cost. Open the same folder in a viewer that does not know wikilinks and [[Project plan]] shows up as literal text. If you publish notes to GitHub or a static site, expect to convert them.

How to write them in MiaoYan

Write the note title between double brackets, without the .md extension:

See [[Project plan]] for next steps, and [[Meeting notes 2026-10]] for context.

The title is the file name without its extension, so Project plan.md is [[Project plan]]. The match is case-sensitive and exact, so extra characters break the link. MiaoYan's agent skill makes the same point: keep the target aligned with the note title and do not invent alias, heading or block-reference syntax.

This differs from Obsidian. Obsidian documents [[Example|Custom name]] for display text, [[Note#Heading]] for headings and #^block-id for blocks. MiaoYan does not implement any of them. Its index reads everything between the brackets as the title, so [[Project plan|plan]] is a link to a note titled "Project plan|plan", which does not exist.

How MiaoYan implements them

Here is how it works, read from the source.

Pattern matching. The editor and the index both look for [[ followed by text and ]]. The editor highlights the title as a link while you write. The index uses a separate pattern that takes any run of characters that is not a closing bracket, trims surrounding spaces, and treats the result as the target title.

The index. Each time the note list refreshes, MiaoYan rebuilds the index from the notes in that list and records for each title the set of titles it links to (outgoing links) and the set of titles that link to it (incoming links). It reads the text each note already has loaded. Notes not opened since launch have no loaded text yet, so their links only count once you open or save them. Saving a note updates its entry in the index.

Clicking a link. A wikilink becomes a miaoyan://goto/<title> address, the same URL scheme the miao open command uses. MiaoYan looks for a note with exactly that title. One match opens it. No match shows "Please make sure your title exists~" and creates nothing. Several matches, for example two folders that each contain Meeting notes.md, start a search for that title and show "Found that there are multiple titles of this~". So unique titles are not just tidy, they are what makes a link unambiguous.

Preview and export. For the rendered preview, MiaoYan rewrites each wikilink into an ordinary Markdown link of the form [Title](miaoyan://goto/Title) before rendering, and skips anything inside code spans and fenced code blocks, so an [[example]] in a code sample stays as text. The export path uses the same preparation, which means an exported file contains miaoyan:// links that only work on a Mac with MiaoYan installed.

Copy URL. The "Copy URL" command places this same address on the clipboard, so you can paste a link to a note into another app.

Backlinks show which notes link to the current note. MiaoYan displays them in the document properties panel, opened with Command Option I, next to the word count and the created and modified dates. The line reads "Backlinks:" followed by a count, then one title per line, or "None" when nothing links to the note.

The list is plain text and the titles are not clickable, so use the search field to jump to a linked note.

What goes wrong and how to check

  • A link opens the wrong note or starts a search. Two notes share a title. Rename one, since MiaoYan uses the file name as the identity.
  • "Please make sure your title exists~". The target does not match any file name exactly. Check case, spaces and punctuation, and remember that Project plan.md is Project plan.
  • You renamed a note and links elsewhere stopped working. MiaoYan does not rewrite links in other notes when you rename a file. Search for the old title with the search field, which looks in both titles and bodies, and update the links.
  • Backlinks look incomplete. The index only counts links from notes in the current list whose text is loaded, meaning notes opened or saved since launch. Open the note that holds the link, or save it, and the backlink appears.
  • A link written for another app shows as text. Aliases, heading links and embeds such as ![[image.png]] are Obsidian syntax and MiaoYan does not support them. Convert them to plain titles or standard Markdown.

Use standard Markdown links when the notes will be read outside MiaoYan, such as a GitHub repository, a static site or a README. Use wikilinks for a personal knowledge base that lives in one app, where short titles make linking fast. Mixing both is fine, since MiaoYan renders both.

Related reading: Local-first Markdown notes covers title-as-filename and folder structure, Markdown notes from the terminal shows miao open with titles, and an Obsidian alternative for Mac lists what carries over from a vault.

MiaoYan for Mac is open source on GitHub, and the App Store version covers Mac, iPhone and iPad.

FAQ

No. Use the title only, such as [[Project plan]].

Does MiaoYan support [[Note|alias]] or [[Note#Heading]]?

No. The whole text between the brackets is treated as the title, so those forms do not resolve.

They are left as plain text inside code spans and fenced code blocks.

Is there a graph view?

No. The Mac app does not include a graph view. Backlinks appear as a list in the document properties panel.