# What Are Aliases in Obsidian Frontmatter and How Do They Work? > Learn how Obsidian frontmatter aliases provide alternative titles, making linking flexible and stable even when files are renamed. Master Obsidian note referencing. - Repository: [Steph Ango/obsidian-skills](https://github.com/kepano/obsidian-skills) - Tags: deep-dive - Published: 2026-03-24 --- **Aliases in Obsidian frontmatter are alternative titles that allow you to reference a note using multiple names, enabling flexible linking and maintaining link stability when files are renamed.** Aliases are a core property in Obsidian's YAML frontmatter system that transform how you create and manage wiki-links across your knowledge base. According to the `kepano/obsidian-skills` repository, this feature allows notes to be referenced by names other than their physical filenames, fundamentally changing the linking behavior in your vault. ## How Aliases Work in Obsidian Frontmatter In Obsidian, notes can contain a YAML frontmatter block at the top of the file. One of the default properties described in the repository is **`aliases`**. As documented in [`skills/obsidian-markdown/references/PROPERTIES.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-markdown/references/PROPERTIES.md), aliases are defined as "Alternative names for the note (used in link suggestions)"【/tmp/instagit_b4vv3k6_/skills/obsidian-markdown/references/PROPERTIES.md:12‑15】. When you start typing a link, Obsidian's link-suggestion engine searches not only the file names but also every alias defined in the frontmatter. If a match is found, the suggestion points to the original note, and the rendered link resolves to that note regardless of which alias was used. ## Benefits of Using Aliases in Obsidian Frontmatter The `aliases` property provides three distinct advantages for knowledge management: - **Natural Language References** – Aliases enable shorthand or more intuitive names for files with rigid naming conventions. For example, a file named [`2024-01-10-Team-Meeting.md`](https://github.com/kepano/obsidian-skills/blob/main/2024-01-10-Team-Meeting.md) can carry the alias "Meeting Notes", allowing you to link using the more memorable `[[Meeting Notes]]` syntax. - **Link Stability During Renames** – When you rename a physical file, existing links that use aliases remain functional. By retaining the old filename as an alias after renaming, all previous wiki-links continue to resolve correctly to the new file location. - **Improved Discoverability** – Aliases are indexed alongside titles and tags in Obsidian's search and graph view. This means the graph visualization and search results recognize multiple entry points to the same note, improving navigation throughout your vault. ## Practical Examples of Obsidian Frontmatter Aliases ### Basic Alias Syntax Define aliases in the YAML frontmatter block at the top of your note: ```yaml --- title: Project Alpha aliases: - Alpha Project - PA tags: - work --- ``` This note can now be linked with any of the following wikilinks: `[[Project Alpha]]`, `[[Alpha Project]]`, or `[[PA]]`. ### Linking with Aliases in Wiki-Links You can reference aliased notes naturally within other files: ```markdown # Follow-up Refer to the specs in [[Alpha Project]] for detailed requirements. ``` Even though the actual file name is `Project Alpha.md`, the link resolves correctly because "Alpha Project" is defined as an alias in the frontmatter. ### Maintaining Link Stability After Renames Aliases prevent broken links when reorganizing your vault: 1. Original file: `Meeting Notes 2024-01-10.md` with aliases `["Jan 10 Meeting", "Team Meeting"]`. 2. Rename the file to [`Team-Meeting-Jan-2024.md`](https://github.com/kepano/obsidian-skills/blob/main/Team-Meeting-Jan-2024.md) while keeping the same alias list. All existing links that used `[[Jan 10 Meeting]]` or `[[Team Meeting]]` still point to the renamed file, because Obsidian matches on the alias list rather than the physical filename. ### Combining Aliases with Other Properties Aliases work alongside other frontmatter properties to create rich, discoverable notes: ```yaml --- title: Quarterly Review date: 2024-04-01 aliases: - Q1 Review - Review Q1 tags: - review - finance cssclasses: - highlight-note --- ``` This configuration benefits from tags for search, a CSS class for styling, and multiple aliases for flexible linking. ## Summary - **Aliases** are defined in YAML frontmatter as alternative names for a note, documented in [`PROPERTIES.md`](https://github.com/kepano/obsidian-skills/blob/main/PROPERTIES.md) within the `kepano/obsidian-skills` repository. - They enable flexible wiki-linking using intuitive names rather than restrictive filenames. - Aliases maintain link stability when files are renamed by preserving reference paths. - The graph view and search index include aliases, improving discoverability across your vault. ## Frequently Asked Questions ### What is the purpose of aliases in Obsidian frontmatter? The purpose of aliases in Obsidian frontmatter is to provide alternative titles for a note, allowing it to be referenced by multiple names in wiki-links. According to the source code in [`skills/obsidian-markdown/references/PROPERTIES.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-markdown/references/PROPERTIES.md), these are specifically "Alternative names for the note (used in link suggestions)"【/tmp/instagit_b4vv3k6_/skills/obsidian-markdown/references/PROPERTIES.md:12‑15】. ### How do I format multiple aliases in YAML frontmatter? Format multiple aliases as a YAML list under the `aliases:` key. Each alias should be preceded by a dash and space, allowing Obsidian to parse them as separate entries for link suggestions and search indexing. ### Do aliases affect the graph view in Obsidian? Yes, aliases improve discoverability in the graph view because they are indexed alongside titles and tags. This means the graph visualization recognizes multiple entry points to the same note, though the node itself typically displays the primary filename or title. ### Will links break if I rename a file but keep the aliases? No, links will not break if you maintain the previous name as an alias after renaming. Because Obsidian's link engine matches against the alias list in addition to physical filenames, existing wiki-links using the old alias continue to resolve correctly to the renamed file.