Automatic Linker

🪄 Automatic Linker 🔮

Automatically convert plain text file references into Obsidian wiki links as you write. Keep your knowledge graph connected without manual linking.

Overview

Automatic Linker scans your notes and intelligently converts text that matches file names in your vault into wiki links ([[...]]). Whether you're writing quick notes or maintaining a complex knowledge base, this plugin ensures your notes stay interconnected without interrupting your flow.

Installation

From Obsidian Community Plugins

1. Open Settings → Community plugins
2. Disable Safe mode
3. Browse for "Automatic Linker"
4. Click Install, then Enable

Manual Installation

1. Download the latest release from GitHub Releases
2. Extract main.js, manifest.json, and styles.css to your vault's .obsidian/plugins/automatic-linker/ directory
3. Reload Obsidian and enable the plugin in Settings → Community plugins

Key Features

Automatic Link Conversion

The plugin automatically detects file names in your text and converts them to wiki links. It works seamlessly with:

• Format on Save: Automatically convert links when saving files
• Selected Text: Convert only highlighted text via command palette
• Entire Vault: Batch process all files in your vault at once
• CJK Support: Full support for Japanese, Chinese, Korean, and other CJK languages
• Case Sensitivity: Optional case-insensitive matching

AI Link Enhancer (Beta)

Resolve ambiguous links and correct existing ones using AI:

• Disambiguation: When multiple notes have the same name or alias, the AI selects the most appropriate one based on context.
• Link Correction: Automatically verify and correct existing wiki links if a better candidate is found.
• Local LLM Support: Connect to any OpenAI-compatible local AI server (e.g., LM Studio, Ollama).
• Context-Aware: Uses surrounding text to provide the AI with necessary context for accurate linking.

Smart Namespace Management

Organize large vaults with sophisticated namespace handling:

• Base Directory: Use Obsidian's "Folder to create new notes in" setting as the base directory where folder prefixes are omitted from links
• Proximity-based Linking: Automatically resolve shorthand links to their full namespaced paths
• Namespace Scope: Use automatic-linker-scoped: true in frontmatter to restrict linking to files within the same namespace
• Closest Match Selection: When multiple candidates exist, the plugin selects the file closest to your current note

URL Formatting

Transform raw URLs into readable Markdown links automatically:

• GitHub URLs: Convert https://github.com/user/repo/issues/123 to [user/repo#123](URL)
• GitHub Enterprise: Configure custom GitHub Enterprise domains
• Jira URLs: Format Jira issue links with custom domain support
• Linear URLs: Format Linear issue links
• Page Titles: Fetch and replace bare URLs with [Page Title](URL) format (cached to minimize requests)

Advanced Link Control

Fine-tune linking behavior to match your workflow:

• Alias Support: Reference files by any of their frontmatter aliases
• Prevent Linking: Add automatic-linker-exclude: true to frontmatter to exclude files from auto-linking
• Prevent Self-Linking: Avoid creating links from a file to itself
• Remove Aliases: Automatically strip aliases in specified directories
• Month Note Handling: Ignore single/double digit references (1, 01, 12) unless namespaced
• Date Format Ignoring: Skip date-formatted text (e.g., 2025-02-10) for compatibility with Obsidian Tasks

Quality of Life Features

• Exclude Directories: Prevent auto-linking in specified folders
• Preserve Existing Links: Never reformats already-linked text
• Copy Without Links: Copy note content with wiki links converted back to plain text
• Copy Selection Without Links: Copy selected lines with minimal indentation and wiki links removed (supports path-style links like [[path/to/file]])
• Debug Mode: Detailed logging for troubleshooting
• Load Notices: Optional notifications when files are processed

Commands

Access these commands via the Command Palette (Cmd/Ctrl + P):

Configuration

General Settings

• Format on Save: Enable automatic linking when saving files
• Format Delay: Delay in milliseconds before formatting (useful for plugin integration)
• Respect 'Folder to create new notes in' setting: Use Obsidian's "Folder to create new notes in" setting as the base directory for omitting folder prefixes in links

Link Behavior

• Include Aliases: Include frontmatter aliases when matching text
• Proximity-based Linking: Automatically resolve shorthand to full namespaced links
• Ignore Case: Enable case-insensitive link matching
• Prevent Self-Linking: Don't create links from a file to itself
• Ignore Date Formats: Skip date-formatted text like 2025-02-10

URL Formatting

• Format GitHub URLs: Convert GitHub links to readable format
• GitHub Enterprise URLs: Add custom GitHub Enterprise domains
• Format Jira URLs: Convert Jira issue links
• Jira URLs: Configure Jira domain(s)
• Format Linear URLs: Convert Linear issue links

AI Link Enhancement (Beta)

• Enable AI Link Enhancement: Add a command to resolve links using a local LLM.
• AI API Endpoint: URL of your OpenAI-compatible AI server (e.g., http://localhost:1234/v1).
• AI Model: Name of the model to use (e.g., gemma-2-9b).
• Max Context Length: Number of characters around the link to provide as context to the AI.

Advanced Options

• Replace URLs with Titles: Automatically fetch page titles for bare URLs
• Ignored Domains: Exclude specific domains from URL title replacement
• Exclude Directories: List of directories to skip during auto-linking
• Remove Alias in Directories: Strip aliases from links in specified folders

Integration

• Run Obsidian Linter After Formatting: Chain with Obsidian Linter plugin
• Run Prettier After Formatting: Chain with Prettier plugin
• Show Load Notice: Display notifications when files are loaded
• Debug Mode: Enable verbose logging

Usage Examples

Example 1: Basic Linking

You have files: Python.md, JavaScript.md, pages/TypeScript.md

When you type:

I'm learning Python and JavaScript for web development.

It becomes:

I'm learning [[Python]] and [[JavaScript]] for web development.

Example 2: Proximity-based Linking

With Obsidian's "Folder to create new notes in" set to pages/ and "Respect 'Folder to create new notes in' setting" enabled, along with Proximity-based Linking enabled:

File structure:

pages/
  languages/
    Python.md
    TypeScript.md
  frameworks/
    React.md

Current file: pages/frameworks/React.md

When you type: React uses TypeScript

It becomes: [[frameworks/React]] uses [[languages/TypeScript]]

Example 3: Namespace Scope

File pages/team-a/internal.md has frontmatter:

---
automatic-linker-scoped: true
---

Current file: pages/team-a/notes.md

Typing internal creates [[team-a/internal]] ✅

From pages/team-b/notes.md, typing internal won't link ❌

Example 4: URL Formatting

Before:

Check out https://github.com/obsidianmd/obsidian-releases/issues/1234

After:

Check out [obsidianmd/obsidian-releases#1234](https://github.com/obsidianmd/obsidian-releases/issues/1234)

Example 5: Copy Selection Without Links

When you select part of a nested list:

Selection in editor:

    - Priority about [[PBI]]
        - High priority for near deadline
    - Chapter [[PBI]]
        - Up to 30% [[story point]] in sprint backlog

After running "Copy selection without links", clipboard contains:

- Priority about PBI
	- High priority for near deadline
- Chapter PBI
	- Up to 30% story point in sprint backlog

Features:

• Removes minimal indentation from selected lines
• Converts path-style links: [[path/to/file]] → file
• Preserves relative indentation structure
• Gets full lines even if partially selected

Integration with Obsidian Linter

To avoid conflicts when using both plugins:

1. Disable "Lint on Save" in Obsidian Linter settings
2. Enable "Format on Save" in Automatic Linker settings
3. Enable "Run Obsidian Linter after formatting" in Automatic Linker settings

This ensures Automatic Linker runs first, followed by Linter.

Frontmatter Options

Add these to individual note frontmatter:

---
# Disable automatic linking in this file
automatic-linker-off: true

# Exclude this file from being automatically linked from other files
automatic-linker-exclude: true

# Restrict linking to same namespace only
automatic-linker-scoped: true

# Define aliases for this file (standard Obsidian feature)
aliases: [shortname, alternative-name]
---

Development

Prerequisites

• Node.js 16+
• pnpm (or npm)

Setup

# Clone the repository
git clone https://github.com/kdnk/obsidian-automatic-linker.git
cd obsidian-automatic-linker

# Install dependencies
pnpm install

# Start development mode
pnpm dev

Available Commands

pnpm build              # Build for production
pnpm dev                # Development mode with watch
pnpm test               # Run all tests
pnpm test:watch         # Run tests in watch mode
pnpm tsc:watch          # TypeScript type checking in watch mode

Running Specific Tests

# Run a specific test file
npx vitest run src/path/to/test.ts

# Run tests matching a pattern
npx vitest run -t "test description"

Project Structure

src/
├── main.ts                    # Main plugin entry point
├── settings/                  # Settings UI and types
├── replace-links/             # Core link replacement logic
├── replace-urls/              # URL formatting (GitHub, Jira, Linear)
├── replace-url-with-title/    # Bare URL to titled link conversion
├── exclude-links/             # Link exclusion logic
├── remove-minimal-indent/     # Remove minimal indentation from text
├── trie.ts                    # Trie data structure for efficient matching
└── update-editor.ts           # Editor update utilities

Troubleshooting

Links aren't being created:

• Ensure "Format on Save" is enabled or manually trigger the command
• Verify the file isn't in an excluded directory

Proximity-based Linking not working:

• Ensure "Proximity-based Linking" is enabled in settings
• Check that files are within Obsidian's configured "Folder to create new notes in" directory if the "Respect 'Folder to create new notes in' setting" option is enabled

Conflicts with Obsidian Linter:

• Follow the integration guide above to run plugins in sequence

Performance issues:

• Disable debug mode if enabled
• Consider excluding large directories from auto-linking
• Increase format delay if formatting happens too frequently

Credits

• updateEditor function adapted from obsidian-linter

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Author

Kodai Nakamura

Support

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and community support

If you find this plugin useful, consider starring the repository on GitHub!