Markdown Tools

Overview

This skill provides document conversion to markdown with Windows/WSL path handling support. It helps convert various document formats to markdown and handles path conversions between Windows and WSL environments.

Core Capabilities

1. Markdown Conversion

Convert documents to markdown format with automatic Windows/WSL path handling.

2. Confluence Export Processing

Handle Confluence .doc exports with special characters for knowledge base integration.

Quick Start

Convert Any Document to Markdown

# Basic conversion
markitdown "path/to/document.pdf" > output.md

# WSL path example
markitdown "/mnt/c/Users/username/Documents/file.docx" > output.md

See references/conversion-examples.md for detailed examples of various conversion scenarios.

Convert Confluence Export

# Direct conversion for simple exports
markitdown "confluence-export.doc" > output.md

# For exports with special characters, see references/

Path Conversion

Windows to WSL Path Format

Windows paths must be converted to WSL format before use in bash commands.

Conversion rules:

• Replace C:\ with /mnt/c/
• Replace \ with /
• Preserve spaces and special characters
• Use quotes for paths with spaces

Example conversions:

# Windows path
C:\Users\username\Documents\file.doc

# WSL path
/mnt/c/Users/username/Documents/file.doc

Helper script: Use scripts/convert_path.py to automate conversion:

python scripts/convert_path.py "C:\Users\username\Downloads\document.doc"

See references/conversion-examples.md for detailed path conversion examples.

Document Conversion Workflows

Workflow 1: Simple Markdown Conversion

For straightforward document conversions (PDF, .docx without special characters):

1. Convert Windows path to WSL format (if needed)
2. Run markitdown
3. Redirect output to .md file

See references/conversion-examples.md for detailed examples.

Workflow 2: Confluence Export with Special Characters

For Confluence .doc exports that contain special characters or complex formatting:

1. Save .doc file to accessible location
2. Use appropriate conversion method (see references)
3. Verify output formatting

See references/conversion-examples.md for step-by-step command examples.

Error Handling

Common Issues and Solutions

markitdown not found:

# Install markitdown via pip
pip install markitdown

# Or via uv tools
uv tool install markitdown

Path not found:

# Verify path exists
ls -la "/mnt/c/Users/username/Documents/file.doc"

# Use convert_path.py helper
python scripts/convert_path.py "C:\Users\username\Documents\file.doc"

Encoding issues:

• Ensure files are UTF-8 encoded
• Check for special characters in filenames
• Use quotes around paths with spaces

Resources

references/conversion-examples.md

Comprehensive examples for all conversion scenarios including:

• Simple document conversions (PDF, Word, PowerPoint)
• Confluence export handling
• Path conversion examples for Windows/WSL
• Batch conversion operations
• Error recovery and troubleshooting examples

Load this reference when users need specific command examples or encounter conversion issues.

scripts/convert_path.py

Python script to automate Windows to WSL path conversion. Handles:

• Drive letter conversion (C:\ → /mnt/c/)
• Backslash to forward slash
• Special characters and spaces

Best Practices

1. Convert Windows paths to WSL format before bash operations
2. Verify paths exist before operations using ls or test commands
3. Check output quality after conversion
4. Use markitdown directly for simple conversions
5. Test incrementally - Verify each conversion step before proceeding
6. Preserve directory structure when doing batch conversions