markdown-tools
Converts documents to markdown (PDFs, Word docs, PowerPoint, Confluence exports) with Windows/WSL path handling. Activates when converting .doc/.docx/PDF/PPTX files to markdown, processing Confluence exports, handling Windows/WSL path conversions, extracting images from PDFs, or working with markitdown utility.
When & Why to Use This Skill
Markdown Tools is a comprehensive Claude skill designed to bridge the gap between proprietary document formats and developer-friendly Markdown. It enables seamless conversion of PDFs, Word documents (DOCX), PowerPoint presentations (PPTX), and Confluence exports into structured Markdown files. Beyond simple text conversion, it features specialized utilities for extracting images from PDFs and resolving pathing discrepancies between Windows and WSL (Windows Subsystem for Linux), making it an essential tool for preparing high-quality context for LLMs and technical documentation.
Use Cases
- Technical Documentation Migration: Converting legacy PDF or Word-based manuals into Markdown for version control on platforms like GitHub or GitLab.
- LLM Context Preparation: Transforming complex PowerPoint or PDF reports into clean Markdown text to provide structured, readable input for AI analysis.
- Cross-Platform Workflow Optimization: Using the path conversion utility to handle file references seamlessly when switching between Windows environments and WSL-based development tools.
- Knowledge Base Digitization: Extracting text and embedded images from Confluence exports to rebuild searchable, local knowledge bases or static site generators.
- Automated Image Extraction: Systematically retrieving visual assets from PDF documents and automatically linking them within the generated Markdown file.
| name | markdown-tools |
|---|---|
| description | Converts documents to markdown (PDFs, Word docs, PowerPoint, Confluence exports) with Windows/WSL path handling. Activates when converting .doc/.docx/PDF/PPTX files to markdown, processing Confluence exports, handling Windows/WSL path conversions, extracting images from PDFs, or working with markitdown utility. |
Markdown Tools
Convert documents to markdown with image extraction and Windows/WSL path handling.
Quick Start
Install markitdown with PDF Support
# IMPORTANT: Use [pdf] extra for PDF support
uv tool install "markitdown[pdf]"
# Or via pip
pip install "markitdown[pdf]"
Basic Conversion
markitdown "document.pdf" -o output.md
# Or redirect: markitdown "document.pdf" > output.md
PDF Conversion with Images
markitdown extracts text only. For PDFs with images, use this workflow:
Step 1: Convert Text
markitdown "document.pdf" -o output.md
Step 2: Extract Images
# Create assets directory alongside the markdown
mkdir -p assets
# Extract images using PyMuPDF
uv run --with pymupdf python scripts/extract_pdf_images.py "document.pdf" ./assets
Step 3: Add Image References
Insert image references in the markdown where needed:
Step 4: Format Cleanup
markitdown output often needs manual fixes:
- Add proper heading levels (
#,##,###) - Reconstruct tables in markdown format
- Fix broken line breaks
- Restore indentation structure
Path Conversion (Windows/WSL)
# Windows → WSL conversion
C:\Users\name\file.pdf → /mnt/c/Users/name/file.pdf
# Use helper script
python scripts/convert_path.py "C:\Users\name\Documents\file.pdf"
Common Issues
"dependencies needed to read .pdf files"
# Install with PDF support
uv tool install "markitdown[pdf]" --force
FontBBox warnings during PDF conversion
- These are harmless font parsing warnings, output is still correct
Images missing from output
- Use
scripts/extract_pdf_images.pyto extract images separately
Resources
scripts/extract_pdf_images.py- Extract images from PDF using PyMuPDFscripts/convert_path.py- Windows to WSL path converterreferences/conversion-examples.md- Detailed examples for batch operations