How to Create Internal Links in Obsidian Using Wikilinks

Obsidian uses wikilinks—double-bracket syntax [[Note Title]]—to create internal connections between Markdown files that automatically update when notes are renamed or moved.

Obsidian stores all notes as plain Markdown files inside a vault, and internal navigation relies on wikilinks to connect these files without requiring file paths or extensions. According to the obsidian-markdown skill in the kepano/obsidian-skills repository, the wikilink implementation supports multiple targeting variations, from basic note linking to specific headings and block-level references.

Basic Wikilink Syntax

The foundation of internal linking in Obsidian is the double-bracket wrapper. In skills/obsidian-markdown/SKILL.md, the documentation establishes that any text enclosed in [[ and ]] is parsed as an internal reference.

[[Project Plan]]

This syntax links to a note titled "Project Plan" anywhere in the vault. Obsidian automatically resolves the target file regardless of which subfolder it occupies, and it maintains the connection if the file is later renamed or relocated.

Advanced Wikilink Patterns

Beyond basic file linking, the wikilink specification supports four distinct targeting methods for precise navigation.

Custom Display Text

Use the pipe character | to render link text that differs from the target filename. This keeps filenames descriptive while allowing contextual labels in your prose.

[[Project Plan|Current Sprint]]

The link displays as "Current Sprint" but still points to the "Project Plan" note.

Linking to Headings

Target a specific section within another note by appending a hash symbol and the heading text.

[[Project Plan#Milestones]]

When clicked, Obsidian jumps directly to the "Milestones" heading inside "Project Plan". You can also link to headings within the current note using an empty filename:

[[#Conclusion]]

This self-referential pattern navigates to the "Conclusion" heading in the active document.

Linking to Block IDs

For granular targeting, wikilinks support block ID references. Block IDs are unique identifiers assigned to specific paragraphs using a caret (^) followed by an alphanumeric string.

To link to a block, append #^ and the identifier to the note name:

[[Project Plan#^intro-block]]

Defining Block IDs for Wikilink Targets

Before a block ID link functions, the target paragraph must declare its identifier. According to skills/obsidian-markdown/SKILL.md (lines 31-35), place the caret and ID at the end of the target paragraph:

The project kickoff meeting covered scope and timeline. ^intro-block

For list items or blockquotes, place the block ID on the line immediately following the content:

> "Key takeaway from the demo."
^demo-quote

Obsidian indexes these IDs vault-wide, allowing precise deep-linking to individual sentences or list items.

Wikilinks vs. Standard Markdown Links

The skills/obsidian-markdown/SKILL.md documentation (line 19) distinguishes between link types based on destination:

• Wikilinks ([[...]]): Reserved for internal vault connections. Obsidian treats these as first-class references, tracking file renames, folder moves, and deletions to prevent broken links.
• Standard Markdown links ([text](url)): Designed for external URLs and web resources. These do not receive automatic path updates when vault files change.

This architectural separation ensures that internal knowledge graphs remain intact during file reorganizations, while external references maintain static URLs.

Summary

• Vault-based resolution: Wikilinks in Obsidian use [[Note Title]] syntax and resolve relative to the vault root, ignoring folder paths.
• Automatic maintenance: The system tracks file renames and moves, updating all internal references automatically.
• Precision targeting: Append #Heading for section links or #^block-id for paragraph-level links.
• Block ID syntax: Define targets with ^identifier at paragraph end or on the following line for quotes/lists.
• Separation of concerns: Use wikilinks for internal notes and standard Markdown links for external URLs.

Frequently Asked Questions

What happens to wikilinks when I rename a note in Obsidian?

Obsidian automatically updates all [[...]] references throughout the vault to reflect the new filename. Because wikilinks are stored as relative references resolved at runtime, the application tracks these connections in its metadata cache and rewrites the link text when files are renamed or moved via the interface.

Can I use wikilinks to link to a specific paragraph within a note?

Yes. First, add a block ID to the target paragraph by appending ^unique-id to the end of the line. Then create a link using [[Note Title#^unique-id]]. The caret symbol distinguishes block references from heading references, allowing you to link to any sentence or list item annotated with an ID.

How do I display different text than the note title in a wikilink?

Insert a pipe character | inside the brackets between the filename and your desired display text. For example, [[Project Plan|Current Sprint]] renders as "Current Sprint" while linking to "Project Plan.md". This aliasing preserves the canonical filename while allowing contextual link labels in your writing.

Should I use wikilinks or Markdown links for external websites?

Use standard Markdown links [text](https://example.com) for external URLs. According to the obsidian-markdown skill documentation, wikilinks are optimized exclusively for internal vault navigation and receive automatic path updates, whereas Markdown links remain static and are the correct choice for web resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}