Obsidian Internal Links

Overview

This skill enables navigation and exploration of Obsidian's internal link structure by resolving [[link]] references to read connected notes. Use this skill when understanding relationships between notes, following references, or building a comprehensive view of interconnected ideas within an Obsidian vault.

When to Use This Skill

Invoke this skill when:

User asks to "follow links" in an Obsidian note
User wants to "explore connected notes" or "see what this links to"
User requests to "read linked pages" or "show me related notes"
User wants to understand the "knowledge graph" or "note relationships"
User asks to "trace references" or "find all related content"
Working with Obsidian markdown files that contain [[internal links]]

Core Workflow

1. Identify the Starting Note

Determine which Obsidian note to start from. This could be:

A file path provided by the user
The current file being discussed
A note referenced by name or ID

2. Execute the Link Resolver

Use the scripts/resolve_links.py script to analyze the note and follow its links.

Dependencies: The script requires PyYAML. If using UV: uv pip install PyYAML. Otherwise: pip install PyYAML or pip3 install --break-system-packages PyYAML on systems with externally managed Python.

python scripts/resolve_links.py <file-path> --vault <vault-path> --depth <depth> --pretty

Parameters:

<file-path> (required): Path to the markdown file to analyze
--vault (optional): Path to the Obsidian vault (defaults to /Users/tolga/src/tolgaio/brain)
--depth (optional): Maximum recursion depth for following links (default: 1)
- 0 = Extract links but don't follow them
- 1 = Follow direct links and identify their outgoing links
- 2+ = Follow links recursively to the specified depth
--pretty (optional): Format JSON output for readability

Example:

# Follow links one level deep from inbox.md
python scripts/resolve_links.py /Users/tolga/src/tolgaio/brain/0_inbox/inbox.md --depth 1 --pretty

# Just extract links without following them
python scripts/resolve_links.py /path/to/note.md --depth 0

3. Interpret the Results

The script returns a JSON structure containing:

{
  "file": "/path/to/source.md",
  "links": [
    {
      "link_text": "digital-garden",
      "display_text": "Digital Garden",
      "resolved": true,
      "target_file": "/path/to/digital-garden.md",
      "content": "# Digital Garden\n\n...",
      "nested_links": [...]  // If depth > 0
    }
  ],
  "broken_links": ["nonexistent-note"]
}

Key fields:

links: Array of resolved link objects
- link_text: The target from [[link_text]] or [[link_text|display]]
- display_text: What's shown to the user (after | or same as link_text)
- resolved: Whether the link target was found
- target_file: Absolute path to the linked file (if found)
- content: Full text content of the linked file
- nested_links: Recursively resolved links (if depth allows)
broken_links: Array of link targets that couldn't be resolved

4. Present the Information

Structure the results for the user based on their request:

For link exploration:

List all linked notes with their titles
Show the hierarchy if depth > 0
Highlight any broken links that need attention

For content synthesis:

Read and summarize the linked notes
Extract relevant sections
Connect ideas across multiple notes

For knowledge mapping:

Describe the relationship structure
Identify central hub notes
Show connection patterns

Link Resolution Strategy

The script resolves links using this priority order:

Frontmatter ID: Checks if the link target matches any note's id: field in YAML frontmatter
Filename: Matches against the filename (without .md extension)
Path-based: For links like [[folder/note]], tries path resolution

Example:

---
id: digital-garden
aliases:
  - My Garden
  - Knowledge Base
---

A link [[digital-garden]] or [[digital-garden|Digital Garden]] will resolve to this note.

Handling Different Link Types

Basic Links

[[note-name]]

Resolves to a note with id: note-name or filename note-name.md

Links with Aliases

[[note-id|Display Text]]

The script extracts note-id as the target and Display Text as what's shown

Heading Links

[[note-name#Heading]]

Currently resolves to the note itself (heading navigation is future enhancement)

Path-Based Links

[[folder/subfolder/note]]

Tries to resolve using the full path, or falls back to just the note name

Embedded Files

![[image.png]]

These are automatically skipped as they're not navigable note links

Managing Recursion

Depth 0 - Extract only:

Lists all links in the starting document
No content loading from linked files
Fast, minimal context usage
Use when you only need to know what's linked

Depth 1 - One level deep (recommended default):

Reads content of directly linked notes
Identifies what those notes link to
Balanced between context and insight
Use for most exploration tasks

Depth 2+ - Deep traversal:

Follows links within linked notes
Can quickly expand to many files
Higher context usage
Use when building comprehensive knowledge maps

Cycle detection: The script tracks visited files to prevent infinite loops when notes link to each other.

Broken Link Handling

When links cannot be resolved:

They're collected in the broken_links array
Processing continues with other links
Report broken links to the user so they can:
- Fix the link
- Create the missing note
- Update references

Example Usage Scenarios

Scenario 1: Following References

User: "What does my inbox note link to?"

python scripts/resolve_links.py /Users/tolga/src/tolgaio/brain/0_inbox/inbox.md --depth 1 --pretty

Present: "Your inbox links to 5 notes: [list them]. Here's a summary of each linked note..."

Scenario 2: Building a Knowledge Graph

User: "Show me how my digital garden notes are connected"

python scripts/resolve_links.py /Users/tolga/src/tolgaio/brain/2_Resources/digital-garden.md --depth 2 --pretty

Present: "Your digital garden connects to [X] notes. The main clusters are... [describe the network]"

Scenario 3: Finding Broken Links

User: "Check if all my project notes have valid links"

python scripts/resolve_links.py /Users/tolga/src/tolgaio/brain/1_Projects/project-x.md --depth 0

Present: "Found 3 broken links: [list them]. These need to be fixed or the target notes created."

Advanced Considerations

Performance

Large vaults (hundreds of files) may take a few seconds to index
Deep recursion (depth 3+) can process many files
Consider using --depth 0 first to see link count before deep traversal

Context Management

Each linked file's content is included in the JSON output
Deep traversal can generate large JSON responses
Be mindful of context window limits when following many links

Vault Configuration

Default vault path: /Users/tolga/src/tolgaio/brain
Override with --vault parameter for different vaults
The script builds an index of all .md files in the vault

Reference Documentation

For detailed information about Obsidian's internal link syntax, variants, and edge cases, refer to references/obsidian-link-syntax.md. This includes:

Complete syntax reference for all link types
Resolution behavior and priority rules
Vault-specific naming conventions
Regular expressions for link extraction
Best practices for link creation

Load this reference when dealing with complex link patterns or unusual syntax.

Resources

scripts/resolve_links.py

Python script that handles link resolution. Capabilities:

Indexes all markdown files in the vault by frontmatter ID and filename
Extracts [[...]] links using regex parsing
Resolves links following the priority order described above
Recursively follows links up to specified depth
Detects cycles to prevent infinite loops
Returns structured JSON output with resolved links and content

references/obsidian-link-syntax.md

Comprehensive documentation covering:

All Obsidian link syntax variations
Link resolution behavior and rules
Vault-specific patterns from /Users/tolga/src/tolgaio/brain
Best practices and common patterns
Edge cases and special considerations