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

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

# 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

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

# 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

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

# 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

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

obsidian-wikilinks-converter

Install Skill

SKILL.md