# Obsidian Linker Automated internal linking tool for Obsidian vaults. This tool creates a clean slate by removing old messy links and adding fresh, high-quality wiki links based on note titles, aliases, and Readwise authors. ## Features - **Clean Slate Approach**: Removes all existing wiki links and creates fresh ones - **Smart Entity Detection**: Links note titles, aliases, and Readwise authors - **Confidence Scoring**: Only creates links with high confidence to avoid false positives - **Safe Operation**: Always creates backups before modifications - **Detailed Reports**: Generates markdown and JSON reports of all changes - **Dry-Run Mode**: Preview changes before applying them ## Installation 1. Install required Python packages: ```bash pip install -r requirements.txt ``` ## Usage ### Preview Changes (Dry Run) ```bash python main.py --dry-run ``` This will: - Scan your entire vault - Find all potential links - Generate a detailed report WITHOUT modifying any files - Save report to `obsidian-linker-report.md` ### Apply Changes ```bash python main.py --apply ``` This will: - Create a backup of all files to be modified - Remove old wiki links - Add new high-quality links - Generate a detailed report - Show you how to restore if needed ### Adjust Confidence Threshold ```bash python main.py --apply --confidence 90 ``` Higher confidence = fewer but more certain links (0-100, default: 80) ### Restore from Backup ```bash python main.py --restore /path/to/backup ``` Or list all backups: ```bash python main.py --list-backups ``` ## Configuration Edit `config.py` to customize: - `MIN_CONFIDENCE`: Minimum confidence score for links (default: 80) - `MAX_LINKS_PER_FILE`: Maximum links to add per file (default: 20) - `MIN_ENTITY_LENGTH`: Minimum characters for linkable entities (default: 3) - `EXCLUDE_FOLDERS`: Folders to skip entirely - `LINK_SOURCE_ONLY_FOLDERS`: Folders that can be linked TO but not modified (e.g., Readwise) ## How It Works 1. **Scan Vault**: Reads all markdown files and parses frontmatter 2. **Strip Old Links**: Removes all existing `[[wiki links]]` (except in Readwise files) 3. **Build Entity Index**: Extracts note titles, aliases, and Readwise authors 4. **Find Matches**: Scans content for entity matches using word boundaries 5. **Validate Positions**: Skips matches inside code blocks, URLs, frontmatter 6. **Score Confidence**: Only creates links with high confidence scores 7. **Apply Links**: Adds clean `[[wiki links]]` to content 8. **Generate Report**: Creates detailed markdown and JSON reports ## Safety - **Dry-run by default**: You must explicitly use `--apply` to modify files - **Automatic backups**: Full backup created before any modifications - **Easy restore**: One command to undo all changes - **Readwise protection**: Never modifies synced Readwise files - **Validation**: Skips code blocks, existing links, URLs, frontmatter ## Reports After running, check: - `obsidian-linker-report.md` - Human-readable report viewable in Obsidian - `obsidian-linker-report.json` - Structured data for programmatic use ## Examples Preview what would happen: ```bash python main.py --dry-run ``` Apply changes with default settings: ```bash python main.py --apply ``` Only very confident links: ```bash python main.py --apply --confidence 95 ``` Restore if something went wrong: ```bash python main.py --restore .vault-backup/20260105_143022 ``` ## Troubleshooting ### "ModuleNotFoundError: No module named 'frontmatter'" Run: `pip install -r requirements.txt` ### "Too many/too few links added" Adjust the confidence threshold: - Lower (e.g., 70): More links, some false positives - Higher (e.g., 90): Fewer links, higher quality Edit `MAX_LINKS_PER_FILE` in `config.py` to change the limit. ### "I want to exclude certain folders" Edit `EXCLUDE_FOLDERS` in `config.py`. ## License MIT License - feel free to modify and use as needed.