markitdown-python

Files (2)

• SKILL.md
• convert_to_markdown.py · scripts/

SKILL.md (first lines)

# MarkItDown Skill

Convert various file formats to Markdown using [microsoft/markitdown](https://github.com/microsoft/markitdown).

## Pre-Check

Before converting any file, follow this check sequence:

### Step 1: Check if markitdown is already in PATH

```powershell
# Windows
Get-Command markitdown -ErrorAction SilentlyContinue
```

```bash
# macOS / Linux
which markitdown || command -v markitdown
```

**If found → skip to [Usage](#usage).**

### Step 2: Check if markitdown exists in ~/.venv

```powershell
# Windows
Test-Path "$env:USERPROFILE\.venv\Scripts\markitdown.exe"
```

```bash
# macOS / Linux
test -f ~/.venv/bin/markitdown && echo "found"
```

**If found → add to PATH for this session, then proceed to [Usage](#usage):**

```powershell
# Windows
$env:PATH = "$env:USERPROFILE\.venv\Scripts;$env:PATH"
```

```bash
# macOS / Linux
export PATH="$HOME/.venv/bin:$PATH"
```

### Step 3: Install (only if Steps 1 and 2 both failed)

```powershell
# Windows
python -m venv "$env:USERPROFILE\.venv"
& "$env:USERPROFILE\.venv\Scripts\pip" install "markitdown[all]"
$env:PATH = "$env:USERPROFILE\.venv\Scripts;$env:PATH"
```

```bash
# macOS / Linux
python3 -m venv ~/.venv
~/.venv/bin/pip install "markitdown[all]"
export PATH="$HOME/.venv/bin:$PATH"
```

---

## Installation Location

MarkItDown is installed in a dedicated venv at `~/.venv`:

| Platform      | Executable                        | pip                           |
|---------------|-----------------------------------|-------------------------------|
| Windows       | `~\.venv\Scripts\markitdown.exe`  | `~\.venv\Scripts\pip.exe`     |
| macOS / Linux | `~/.venv/bin/markitdown`          | `~/.venv/bin/pip`             |

## Supported Formats

- PDF
- PowerPoint (.pptx)
- Word (.docx)
- Excel (.xlsx, .xls)
- Images (EXIF metadata, OCR with plugin)
- Audio (EXIF metadata, speech transcription)
- HTML
- Text-based formats (CSV, JSON, XML)
- ZIP files (iterates over contents)
- YouTube URLs
- EPubs
- Outlook messages (.msg)

## Usage

### Command-Line (preferred for simple conversions)

```powershell
# Windows - convert a file to markdown (output to stdout)
markitdown "path\to\file.pdf"

# Save output to a file
markitdown "path\to\file.pdf" -o output.md
```

```bash
# macOS / Linux
markitdown path/to/file.pdf
markitdown path/to/file.pdf -o output.md
cat path/to/file.pdf | markitdown
```

### Automated Conversion Script

For repeatable file conversions, use `scripts/convert_to_markdown.py`. Run it with the current `python` when that environment can import `markitdown`; use the dedicated virtual-environment interpreter only when the current environment does not have the dependency. The script converts the input, removes NUL characters from generated text, writes UTF-8 without a BOM, validates that the output is not empty, and prints the output path.

```powershell
python "$env:USERPROFILE\.agents\skills\markitdown-python\scripts\convert_to_markdown.py" ".\input.msg" -o ".\output.md"
```

```bash
python ~/.agents/skills/markitdown-python/scripts/convert_to_markdown.py ./input.msg -o ./output.md
```

From Jansen611/Agent-Skills, MIT.

More from Jansen611/Agent-Skills