obsidian-wikilinks-converter

name	obsidian-wikilinks-converter
description	Convert Obsidian WikiLinks ([[...]]) to standard Markdown links ([...](...)) for GitHub compatibility. This skill should be used when users need to make README files or other Markdown documents GitHub-compatible while maintaining Obsidian functionality, or when batch converting WikiLinks across multiple files.
license	MIT

Obsidian WikiLinks Converter

This skill provides tools and workflows for converting Obsidian WikiLinks ([[...]]) to standard Markdown links ([...](...)) to ensure GitHub compatibility.

When to Use This Skill

Use this skill when you need to:

• 📄 Make README.md files GitHub-compatible
• 🔗 Convert WikiLinks to standard Markdown in batch
• 🔄 Maintain dual compatibility (Obsidian + GitHub)
• 📝 Prepare Obsidian notes for publishing to platforms that don't support WikiLinks

Core Concepts

WikiLink Formats

Obsidian supports several WikiLink patterns:

WikiLink Format	Standard Markdown	Notes
[[file]]	[file](file.md)	Simple file reference
[[path/file]]	[file](path/file.md)	With path
[[file|Display]]	[Display](file.md)	Custom display text
[[../path/file]]	[file](../path/file.md)	Relative path

Conversion Rules

1. Display Text Priority:

   • If | separator exists: use specified display text
   • Otherwise: use filename (without path and extension)

2. Path Handling:

   • Preserve relative paths (../, ./)
   • Add .md extension if missing
   • URL-encode spaces: My File.md → My%20File.md

3. Special Cases:

   • [[README]] → [README](README.md)
   • [[folder/README]] → [README](folder/README.md)

Usage

Quick Start

# Preview changes without modifying files
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py --dry-run

# Convert all README.md files in current directory
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py

# Convert a specific file
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py --file path/to/file.md

# Convert all README files in a specific directory
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py --root ./06-AI

Common Workflows

Workflow 1: Convert All README Files

For maintaining GitHub-compatible documentation:

# 1. Review what will be changed
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py --dry-run

# 2. Apply changes
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py

# 3. Verify in Git
git diff

Workflow 2: Convert Single File

For preparing a specific document:

# Convert and review
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py \
  --file Level-6-Best-Practices/README.md

Workflow 3: Batch Convert by Pattern

For converting all files matching a pattern:

# Find and convert all README files
find . -name "README.md" -type f | while read file; do
  python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py --file "$file"
done

Implementation Details

Conversion Logic

The converter uses regex pattern matching with the following logic:

# Pattern: [[content]]
pattern = r'\[\[([^\]]+)\]\]'

# Conversion function
def convert(match):
    content = match.group(1)

    # Split by | for display text
    if '|' in content:
        path, display = content.split('|', 1)
    else:
        path = content
        display = path.split('/')[-1]  # Use filename

    # Add .md extension if needed
    if not path.endswith('.md'):
        path = path + '.md'

    # URL encode spaces
    path = path.replace(' ', '%20')

    return f'[{display}]({path})'

Edge Cases Handled

1. Code Blocks: WikiLinks inside code blocks are NOT converted
2. Front Matter: YAML front matter is preserved
3. Empty Links: [[]] is skipped
4. Special Characters: Properly escaped in URLs
5. Nested Paths: Relative and absolute paths preserved

Best Practices

1. Always Use Dry-Run First

# GOOD: Preview before applying
python3 convert.py --dry-run
python3 convert.py

# BAD: Direct conversion without review
python3 convert.py

2. Commit Before Conversion

# Save current state
git add .
git commit -m "Before WikiLinks conversion"

# Apply conversion
python3 convert.py

# Review and commit
git diff
git add .
git commit -m "Convert WikiLinks to standard Markdown"

3. Test on Sample Files First

# Test on a single file
cp README.md README.md.backup
python3 convert.py --file README.md
diff README.md README.md.backup

4. Use Obsidian-Compatible Markdown

Both Obsidian and GitHub support standard Markdown links:

# ✅ RECOMMENDED: Works everywhere
[Display Text](path/to/file.md)

# ❌ Obsidian-only: Breaks on GitHub
[[path/to/file|Display Text]]

Limitations

1. Code Block Detection: Basic implementation may convert WikiLinks in code blocks
2. Image Links: Assumes all WikiLinks are document links (not images)
3. Section Links: [[file#section]] not fully supported yet
4. Block References: [[file^block]] not supported

Future Enhancements

• Preserve WikiLinks in code blocks/inline code
• Support image WikiLinks ![[image.png]]
• Handle section links [[file#section]]
• Support block references [[file^block]]
• Interactive mode with confirmation prompts
• Git integration for auto-commit

Troubleshooting

Issue: Script Not Found

# Solution: Run from repository root
cd /path/to/ObsidianVault
python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py

Issue: Permission Denied

# Solution: Make script executable
chmod +x .claude/skills/obsidian-wikilinks-converter/scripts/convert.py

Issue: Unexpected Conversions

# Solution: Use --dry-run to preview
python3 convert.py --dry-run --file problematic-file.md

References

• Obsidian Help: Internal Links
• GitHub Markdown Spec
• Markdown Links Best Practices

Script Location

The conversion script is located at:

.claude/skills/obsidian-wikilinks-converter/scripts/convert.py

Invoke with: python3 .claude/skills/obsidian-wikilinks-converter/scripts/convert.py --help