Canonical Technical Definition

A compact double-bracket syntax ([[Target Note]]) that creates an associative hyperlink between two documents without requiring explicit file paths or extensions.

A WikiLink is an internal referencing mechanism that uses double square brackets ([[Note Title]]) to connect ideas across documents without specifying brittle relative file paths or file extensions.

Originally invented by Ward Cunningham in 1995 for the first wiki (WikiWikiWeb), the bracketed link syntax was later refined by Wikipedia and adopted by modern note-taking applications like Roam Research, Obsidian, Logseq, and Oyma.

Standard CommonMark links ([Title](folder/subfolder/file.md)) were created for static web hierarchies. In a personal knowledge management system, note locations change frequently as ideas mature.

WikiLinks solve three fundamental problems:

  1. Frictionless linking: When writing prose, stopping to calculate relative directory traversal (../../notes/) interrupts cognitive focus. Writing [[Machine Learning]] takes less than a second.
  2. Resilience to folder reorganization: Because a WikiLink references the note title rather than its path, you can move Machine Learning.md into an archive or subfolder without breaking links.
  3. Piped aliases: You can display alternative anchor text while preserving the destination link: [[Quarterly Business Review|Q3 Review]].
In our discussion with [[Elena Rostova]], we reviewed the proposed
[[Privacy Architecture]] and agreed on [[2026-10-09 Q4 Roadmap]].

When a modern editor like Oyma encounters a WikiLink:

  1. It queries the local SQLite index for an exact file match matching the link target.
  2. If no direct match is found, it checks note aliases defined in YAML frontmatter.
  3. In live preview, clicking the link opens the destination note; hovering displays an instant hover popover preview.

In Oyma on macOS:

  • Typing [[ triggers lightning-fast fuzzy autocomplete matching across note titles, aliases, and section headings.
  • Renaming any note automatically triggers a safe, background refactor that rewrites all incoming [[WikiLinks]] across your vault.
  • WikiLinks form the connective tissue of Oyma‘s interactive local and global Graph View.

WikiLinks support three standard syntactic extensions that provide flexible linking options:

  • Heading links: [[Note Title#Specific Section]] navigates directly to a target heading within the document.
  • Piped aliases: [[Note Title|Custom Anchor Text]] displays custom prose while preserving the underlying file destination.
  • Block references: [[Note Title#^block-id]] targets an atomic paragraph or list item identified by a caret tag.

Because WikiLinks do not require file paths or extensions, your knowledge base remains fluid, adaptable, and resilient against directory reorganization over decades of writing.

Frequently asked questions about Bidirectional WikiLinks

How does a [[WikiLink]] differ from a standard Markdown link?

Standard Markdown links ([Text](path/to/doc.md)) require hard-coded file paths and extensions that break when files are moved. A [[WikiLink]] resolves dynamically by file name across the entire vault.

Can I link to a specific heading or block using a WikiLink?

Yes. Use a hash symbol for headings ([[Note#Heading]]) or a caret symbol for block references ([[Note#^block-id]]).

How do WikiLinks work in Oyma on macOS?

Typing [[ in Oyma opens an instant autocomplete menu of all notes in your vault. Renaming a note automatically rewrites all [[WikiLinks]] pointing to it across your files.