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

•
Display Text Priority:
- •If | separator exists: use specified display text
- •Otherwise: use filename (without path and extension)
•
Path Handling:
- •Preserve relative paths (../, ./)
- •Add .md extension if missing
- •URL-encode spaces: My File.md → My%20File.md
•
Special Cases:
- •[[README]] → [README](README.md)
- •[[folder/README]] → [README](folder/README.md)

Usage

Quick Start

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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:

python

# 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

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

Best Practices

1. Always Use Dry-Run First

bash

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

# BAD: Direct conversion without review
python3 convert.py

2. Commit Before Conversion

bash

# 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

bash

# 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:

markdown

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

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

Limitations

•Code Block Detection: Basic implementation may convert WikiLinks in code blocks
•Image Links: Assumes all WikiLinks are document links (not images)
•Section Links: [[file#section]] not fully supported yet
•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

bash

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

Issue: Permission Denied

bash

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

Issue: Unexpected Conversions

bash

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

References

Script Location

The conversion script is located at:

code

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

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