Obsidian Internal Links: Wikilinks, Markdown, Aliases & Backlinks

Obsidian internal links connect notes, attachments, headings, and blocks inside one vault. The quick answer is: type [[, choose a note, add # for a heading, #^ for a block, and | for custom display text. Obsidian creates wikilinks by default, while standard Markdown links are useful when files must work in other editors.

This guide explains the syntax, the tradeoffs between link types, and a repeatable way to connect daily notes, projects, meetings, and reference material. It follows the current Obsidian internal links documentation and adds practical troubleshooting for the cases that cause broken or confusing links.

Here’s what we’ll cover:

• Basic internal links and how they work

• Wikilinks versus markdown format

• Linking to specific headings and blocks

• Efficient link creation workflows

• Customizing link text and aliases

• Backlinks, graph view, and linked thinking

• Practical use cases for projects, research, and learning

Internal Links in Obsidian: The Basics

An internal link connects one file in your vault to another—whether that’s a note, attachment, heading, or block. The default method uses wikilinks: type [[Meeting notes]] or [[2026-03-16 Daily Log]] to create a link to those files.

When you click a link to a note that doesn’t exist yet (shown in red or grayed-out), Obsidian will automatically create that new note for you. This means you can link generously without worrying whether the target note exists.

After typing [[, Obsidian’s search dialog suggests matching file name options from your vault. Links are not case sensitive, so [[project alpha]] and [[Project Alpha]] point to the same note. Navigate through suggestions and press enter to select.

One powerful feature: Obsidian can automatically update internal links when you rename a note. Enable this in Settings → Files & Links → Automatically update internal links. Keeping descriptive filenames from the start still makes search and link suggestions easier.

Supported Link Formats: Wikilinks vs Markdown Links

Obsidian supports two internal link formats. The default wikilink syntax looks like [[Project Alpha]]—compact and readable. The alternative markdown format follows standard conventions: Project Alpha.

You can switch between formats in Settings → Files & Links → Use [[Wikilinks]]. When should you choose markdown format? It’s preferable when syncing raw files with GitHub, publishing to static site generators, or sharing with other markdown editors that don’t understand wikilinks.

Markdown links require URL encoding—spaces become %20, and special characters need escaping. For example, a link to Q2 2026 Roadmap.md becomes [Q2 2026 Roadmap](Q2%202026%20Roadmap.md). Avoid characters like #, |, ^, :, and % in filenames because they have special meanings in Obsidian’s link syntax.

Which Obsidian link format should you use?

Use the smallest link type that solves the reader’s navigation problem:

Need	Syntax	Best fit	Main tradeoff
Connect two notes quickly	[[Project Alpha]]	An Obsidian-first vault	Other Markdown editors may not parse it
Share a portable Markdown file	[Project Alpha](Project%20Alpha.md)	Git repositories and mixed tools	Paths need URL encoding and maintenance
Jump to a section	[[Project Alpha#Timeline]]	Project plans and long notes	Breaks if the heading is renamed manually
Cite one paragraph or list item	[[Project Alpha#^decision]]	Research and meeting decisions	Block references are Obsidian-specific
Keep readable text with a stable target	`[[Project Alpha	website redesign]]`	Natural sentences and aliases

This makes the choice concrete: use wikilinks for everyday vault navigation, Markdown when interoperability matters, heading links for stable sections, and block links only when paragraph-level precision is worth the portability tradeoff.

Linking to Files, Headings, and Blocks

You can link to three target types: entire files, specific headings within files, and precise blocks of text.

Linking to files is straightforward—type [[Project Alpha]] for notes. For attachments like images or PDFs, include the extension: [[Figure 1.png]]. To embed an attachment inline rather than just linking, add an exclamation mark: ![[Figure 1.png]].

Linking to headings uses the # symbol after the note title. For example, [[Project Alpha#Timeline]] links directly to the Timeline heading in that note. For a heading in the current note, type [[# and choose from the suggestions. To search headings across the vault, type [[## followed by a search term.

Linking to blocks offers the finest precision. Add a caret ID such as ^decision to a paragraph or list item, then reference it with [[Project Alpha#^decision]]. Type ^ after a note name to see available blocks. Block references are Obsidian-specific, and Obsidian does not support links to specific parts of quotations, callouts, or tables; use a heading when the destination must remain portable.

Creating Links Efficiently: Typing, Drag-and-Drop, and Workflows

Beyond manual typing, several methods help you create links faster.

The typing method works well once you build muscle memory: type [[, use the interactive search dialog to filter notes, then press enter to select or create a new note. You can also paste a file name and wrap it in [[ ]] to convert plain text into a link.

Drag-and-drop offers another approach. Drag a file from the file explorer into your editor to create a link automatically. This works especially well for attachments or recently created notes whose titles you can’t quite remember.

Don’t confuse internal links with “Copy Obsidian URL”—the latter produces obsidian://open?vault=… links meant for use outside Obsidian in separate app contexts. Standard internal links are what you want for connecting other notes within your vault.

A practical workflow for daily notes: at the top of [[2026-03-16 Daily Log]], quickly link to today’s meetings like [[Q2 2026 Roadmap]] and [[Client – Acme Corp]]. Use autocomplete to create these reference connections in seconds.

Customizing Link Text, Aliases, and Display

The link target and visible text can differ, which improves readability without changing filenames.

With wikilinks, use the pipe syntax: [[Atomic Habits|James Clear – Atomic Habits]]. The document displays “James Clear – Atomic Habits” but links to the “Atomic Habits” note. In markdown format, the display text comes first: James Clear – Atomic Habits.

For global alternate titles, add aliases in YAML frontmatter:

aliases: [Atomic Habits, AH, James Clear Book]

Start typing an alias in an internal-link suggestion and select the result. Obsidian creates a piped link such as [[Atomic Habits|AH]], keeping the canonical note target stable while showing the shorter name.

The distinction matters: display text is per-link and context-specific, while aliases are reusable names stored on the target note. Do not assume a bare [[AH]] will resolve to the note whose alias is AH; if the suggestion produces [[Atomic Habits|AH]], keep that canonical target. This avoids the alias confusion reported by users in the Obsidian Forum.

Choose descriptive filenames like “Morning Routine Template” rather than “Note1” to minimize reliance on workarounds—and if you want a head start, these ready-made Obsidian templates come with sensible naming baked in.

Backlinks, Graph View, and Linked Thinking

Every internal link automatically creates a backlink in the target note, visible in the Backlinks pane. When [[Atomic Habits]] appears in your reading notes, habit tracking, and coaching session notes, those connections surface automatically.

The graph feature visualizes your vault as nodes (notes) connected by edges (links). The local graph shows connections around a single note; the global graph displays your entire network. Clusters emerge around projects, themes like productivity, or people—revealing structure you might not have consciously created.

This approach represents linked thinking: building a web of ideas similar to a personal wiki or digital Zettelkasten. Instead of relying solely on folder structure or tags, links create multiple pathways to the same knowledge—the same philosophy behind most dedicated personal knowledge management tools.

A simple habit: spend 10 minutes weekly traversing backlinks from a hub note like [[Personal Knowledge System]]. You’ll discover connections and find pages you’d forgotten, sparking new ideas and writing directions.

Practical Use Cases: Projects, Research, and Learning

Here’s how linking works in real workflows.

For project management, create a hub note like [[Project – Website Redesign 2026]] that links outward to tasks, meeting notes, design docs, and status updates. Tags like #status/in-progress help, but links and backlinks are the backbone of project clarity.

For research and writing, a master article note such as [[Article – Obsidian for Researchers]] links to source notes, highlighted quotes, and outlines. Block links let you cite specific claims with precision—useful when revisiting research months later.

For learning, link highlights from books like [[Deep Work]] or [[Thinking, Fast and Slow]] to topic notes like [[Focus]] and [[Decision Making]]. As you accumulate links, backlinks surface patterns across your reading that you’d never spot otherwise.

Don’t overthink it. Mention and link generously even when a note is mostly empty. These stubs mature into meaningful knowledge nodes over time, and the point is building connections now.

If your vault connects work rather than only reference material, Obsibrain’s P.A.R.A. structure, smart projects, and daily planning provide a ready-made destination for those project, task, and review links. That is useful when the hard part is maintaining the system after the initial setup, not learning another bracket pattern.

Interoperability, Settings, and Best Practices

Key settings live in Settings → Files & Links: toggle Use [[Wikilinks]], set New link format, enable Automatically update internal links, and configure your default attachment folder.

When sharing markdown with colleagues or publishing online, standard markdown links are safer—other tools won’t parse wikilinks. Disabling wikilinks converts your visible links to markdown form automatically.

Organize attachments consistently (eg /Attachments or /Projects/Book Title/Attachments) and enable relative link paths to keep everything portable across devices. For filenames, use descriptive patterns with dates where relevant: 2026-03-16 – Team Sync – Marketing. Avoid problematic characters.

Good habits for vault health: descriptive titles, liberal linking, regular backlink review, and thoughtful settings from the start. Hope this process becomes second nature within a few weeks.

Obsidian Internal Links Troubleshooting Checklist

When a link behaves unexpectedly, check the target and the link type in this order:

1. The link is red or opens the wrong note: use autocomplete to select the canonical filename, especially when two folders contain similar names.
2. An alias appears broken: use the generated piped form, such as [[Canonical note|Short name]], instead of relying on a bare alias.
3. A Markdown link does not open: check the relative path and encode spaces as %20; confirm the file extension for attachments.
4. A backlink is missing: confirm the source contains an actual internal link, not only plain text. Then check Linked mentions separately from Unlinked mentions in the Backlinks pane.
5. A block link is fragile: give the block a readable ID containing letters, numbers, and dashes. Use a heading link instead if the note must render outside Obsidian.

For a small vault-health pass, choose one hub note, add links to its active projects, connect each project to its next actions and meeting notes, then review the hub’s backlinks during your next daily or weekly review. This gives linking a job instead of turning the graph into a decorative map.

Conclusion: Making Obsidian Linking a Daily Habit

Linking is the core mechanic that transforms Obsidian from a note storage tool into a personal knowledge system. Every connection you create adds value that compounds over time, making your vault increasingly useful for future writing, research, and thinking.

Start with one simple practice: add at least three new links whenever you create or review a note. You don’t need a perfect structure on day one. The connected network of notes matures naturally over weeks and months of regular use.

Once comfortable with basic obsidian linking, explore plugins like Dataview or advanced search features that build on your existing link structure. The foundation you’re building now supports whatever sophisticated workflows you’ll want in the future.