Obsidian Basics: Aliases

TL;DR

Aliases in Obsidian (introduced in version 0.9.16) let one document be referenced by multiple alternate names.

Briefing Cornell Notes

Briefing

Aliases in Obsidian—introduced in version 0.9.16—let users define multiple names for the same document, so searches, tasks, and backlinks stay connected even when people refer to something in different ways. The practical payoff is simple: writing “jane,” “wife,” “partner,” or “significant other” can all point to one underlying page, keeping related notes from fragmenting across inconsistent wording.

The setup happens at the very top of a document. Users add a metadata block using three dashes, then the line `aliases: [ ... ]`. Inside the square brackets, they list every alternate term separated by commas. In the example, a page named “jane appleseed” is treated as a single identity (the wife), and the aliases array includes “jane,” “wife,” “partner,” and “significant other.” Once saved, Obsidian surfaces these new aliases in the document preview, with an arrow indicator showing that the words will be rewritten to the same page.

That rewrite behavior matters when capturing daily work. A daily note includes tasks like “ask jane how her day went” and “buy wife a valentine’s day present,” plus a line such as “had a good chat with jane appleseed.” Without aliases, Obsidian would struggle to treat those references as the same target. With aliases enabled, backlinks become more complete: the backlink section for “jane appleseed” pulls in not only direct mentions of the page name, but also the alias terms used elsewhere. Hovering over those backlink entries and clicking reveals that Obsidian creates clean links that resolve through the alias mapping.

Aliases also streamline linking while writing. When typing a note, users can insert links using double square brackets; Obsidian offers the alias option under the target page. For instance, typing “hopefully my partner” and then using `[[...]]` allows selecting the alias “partner” under “jane appleseed,” so the reference stays consistent without forcing the writer to remember the canonical page title.

The result is a workflow shift: fewer missed connections, more reliable backlinking, and less friction when capturing information in both personal and professional contexts. The creator credits aliases as a frequently used feature that improves day-to-day productivity, especially after adopting Obsidian as a primary information-gathering tool.

Cornell Notes

Obsidian aliases (added in version 0.9.16) let one document be referenced by multiple alternate names. Users define them at the very top of a page using a YAML-style block: `aliases: [jane, wife, partner, significant other]`. Once set, Obsidian rewrites those terms to the same page, so tasks and notes that use different wording still generate accurate backlinks. This also improves linking while typing, since double-bracket links can surface alias options under the canonical page. The practical value is fewer fragmented references and more complete connection-building across daily notes.

How do aliases work in Obsidian, and what problem do they solve?

Aliases map multiple words to a single document. In the example, the page “jane appleseed” represents one person, but the writer may refer to her as “jane,” “wife,” “partner,” or “significant other.” With aliases enabled, those different terms are rewritten to the same page, so tasks and mentions in daily notes still connect back to the correct document instead of splitting into separate, unlinked references.

What is the exact format and placement required to define aliases?

Aliases must be defined at the very top of the document. The syntax uses three dashes to start a metadata block, then a line like `aliases: [ ... ]`, followed by three dashes to close it. Inside the square brackets, alternate names are listed and separated by commas (e.g., `aliases: [jane, wife, partner, significant other]`).

What changes in backlinks once aliases are defined?

Backlinks for the canonical page expand beyond direct mentions of the page title. In the example, the “jane appleseed” backlink section includes references created using alias terms like “wife” and “partner,” not just “jane appleseed.” Clicking or linking from those backlink entries shows Obsidian generating links that resolve through the alias mapping.

How do aliases affect tasks and notes that mention the same entity differently?

Tasks and notes that use alias terms are treated as references to the same underlying page. For example, a daily note containing tasks such as “ask jane how her day went” and “buy wife a valentine’s day present,” plus a sentence like “had a good chat with jane appleseed,” all point back to the “jane appleseed” page through the alias rewrite behavior.

How can writers insert links using aliases while typing?

While writing, users can type double square brackets to bring up link options. Under the canonical page (e.g., “jane appleseed”), Obsidian can show alias choices (e.g., “partner”). Selecting the alias option allows the reference to match the wording used in the sentence while still linking to the correct page.

Review Questions

Where in a document must the aliases definition be placed, and what happens if it isn’t at the top?
In the example identity “jane appleseed,” which alias terms were listed, and how did they change what appeared in backlinks?
When linking text in Obsidian, how do double square brackets help you use an alias without manually typing the canonical page name?

Key Points

1
Aliases in Obsidian (introduced in version 0.9.16) let one document be referenced by multiple alternate names.
2
Alias definitions must be placed at the very top of the document using a metadata block with `aliases: [ ... ]`.
3
Once aliases are set, Obsidian rewrites alias terms to the same page, improving consistency across daily notes.
4
Backlinks become more complete because mentions using alias terms resolve to the canonical document.
5
Double-bracket linking can surface alias options under the target page, making it easier to link while writing.
6
Using aliases reduces missed connections when tasks and notes refer to the same entity with different wording.

Highlights

Aliases turn inconsistent wording—like “jane,” “wife,” and “partner”—into links that all resolve to one page.

Backlinks for the canonical document expand to include mentions made using alias terms, not just the page title.

Double-bracket linking can offer alias choices, letting writers keep their natural phrasing while still linking correctly.

Topics

Obsidian Aliases
YAML Metadata
Backlinks
Task Linking
Productivity Workflow