MarkItDown

MarkItDown Skill

Documentation and utilities for converting documents to Markdown using Microsoft's MarkItDown library.

Note: This skill provides documentation and a batch script. The actual conversion is done by the markitdown CLI/library installed via pip.

When to Use

Use markitdown for:

• 📄 Fetching documentation (README, API docs)
• 🌐 Converting web pages to markdown
• 🔗 Analyzing a webpage link / URL the user shared — summarize, extract, translate, or deposit (沉淀) its content into a knowledge base
• 📝 Document analysis (PDFs, Word, PowerPoint)
• 🎬 YouTube transcripts
• 🖼️ Image text extraction (OCR)
• 🎤 Audio transcription

Quick Start

# Convert file to markdown
markitdown document.pdf -o output.md

# Convert URL
markitdown https://example.com/docs -o docs.md

Supported Formats

Installation

The skill requires Microsoft's markitdown CLI:

pip install 'markitdown[all]'

Or install specific formats only:

pip install 'markitdown[pdf,docx,pptx]'

Common Patterns

Fetch Documentation

markitdown https://github.com/user/repo/blob/main/README.md -o readme.md

Convert PDF

markitdown document.pdf -o document.md

Batch Convert

# Using included script (run with the Python that has markitdown installed)
python "/scripts/batch_convert.py" docs/*.pdf -o markdown/ -v
#  = this skill's own directory (the folder containing this SKILL.md).
# On Linux servers where `markitdown` is installed system-wide, just use
#   python3 "/scripts/batch_convert.py" ...   (markitdown is on the system python3).
# WorkBuddy (Windows): use the managed Python that has markitdown, e.g.
#   ~/.workbuddy/binaries/python/envs/default/Scripts/python.exe ; do NOT rely on a system
#   python that lacks markitdown.

# Or shell loop
for file in docs/*.pdf; do
  markitdown "$file" -o "${file%.pdf}.md"
done

Token-Saving Workflow (给 AI 减负)

Large, richly-formatted documents (PDFs, PPTX, DOCX, scanned images) carry heavy layout / font / header / footer / embedded-object noise that inflates token cost. Converting to plain Markdown first strips that noise so the AI ingests only the semantic content — typically cutting token usage by 80%+ versus feeding the raw file.

When to apply (proactively): whenever a user asks to "总结 / 分析 / 提取 / 问答 / 翻译 / 沉淀(沉积)为知识库" a file or a webpage link / URL that is not already plain text (.md/.txt/.csv/.json). This is the single most common cause of wasted tokens in document Q&A, and the most reliable way to faithfully ingest a web page (convert the link to Markdown first, then summarize / deposit).

Steps:

1. Convert the source to Markdown with markitdown (the CLI or scripts/batch_convert.py). For a webpage link, just pass the URL: markitdown "https://..." -o page.md

2. Feed the resulting Markdown to the AI instead of the raw file / raw HTML.

3. Report the cost (and, for PDF/images/web pages, the saving) locally with scripts/token_saver.py:

   # PDF/images: pass --pages to estimate the raw baseline
   python "/scripts/token_saver.py" document.pdf -o document.md --pages 100
   # any format: pass a trusted baseline explicitly
   python "/scripts/token_saver.py" document.pdf --raw-estimate 120000
   # web page: baseline = raw HTML size (estimate), Markdown = converted size
   python "/scripts/token_saver.py" page.md --raw-estimate $(( $(curl -s "https://..." | wc -c) / 4 ))
   

   It prints the approximate Markdown token cost (the actual AI cost) and, with --emit-json, one machine-readable JSON line you can pipe into your own logging or metrics pipeline. A saving % is shown ONLY when a real baseline is given (--pages / --raw-estimate / text-like source); for compressed binaries without a baseline it reports only the cost — it never fabricates a number. All figures use a chars/4 heuristic and are estimates.

4. For batch, convert a whole folder to .md first, then analyze the .md files.

Why it matters: a 100-page PDF fed raw may cost ~10× the tokens of its cleaned Markdown; the extra tokens buy no information. Details and the estimate methodology: TOKEN-SAVER.md.

Python API

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

Troubleshooting

"markitdown not found"

pip install 'markitdown[all]'

OCR Not Working

# Ubuntu/Debian
sudo apt-get install tesseract-ocr

# macOS
brew install tesseract

What This Skill Provides

See Also

• USAGE-GUIDE.md - Detailed examples
• reference.md - Full API reference
• Microsoft MarkItDown - Upstream library