MarkItDown

Self-hosted document-to-Markdown converter running on labmini-01 at md.carloselugo.com.

Built with FastAPI + markitdown by Microsoft. Drop any document, get clean Markdown output in the browser.

Stack

Layer	Tech
Backend	FastAPI + markitdown
Server	Uvicorn (python:3.12-slim)
Reverse proxy	Caddy (automatic SSL)
Container	Docker Compose
Network	`web_web-net` (shared with main stack)

Supported Formats

Category	Formats
Documents	PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, EPUB, MSG
Web / Data	HTML, HTM, CSV, JSON, XML
Archives	ZIP (converts each file inside)
Images	PNG, JPG, JPEG, GIF, WEBP, BMP (OCR via AI)
Audio	MP3, WAV, M4A (transcription via AI)
Text	TXT, MD, RST

Max file size: 50 MB

File Structure

/opt/markitdown/
├── docker-compose.yaml
├── Dockerfile
├── main.py                  # FastAPI app — /convert endpoint
├── requirements.txt
├── static/                  # Empty — assets are inline
└── templates/
    └── index.html           # UI: drag & drop, output panel

API

Method	Path	Description
GET	`/`	Web UI
POST	`/convert`	Upload file, returns `{ markdown, filename, size_kb, chars }`

Example

curl -X POST https://md.carloselugo.com/convert \
  -F "file=@document.pdf" | python3 -m json.tool

Deploy

cd /opt/markitdown
docker compose up -d --build

Caddy block in /opt/web/Caddyfile:

md.carloselugo.com {
    import security_headers
    reverse_proxy markitdown:8000
    log {
        output file /var/log/caddy/markitdown.log
        format json
    }
}

Notes

The ffmpeg warning on startup is harmless — only affects audio transcription, which requires an AI key to use.
Images and audio transcription require an Anthropic or OpenAI API key passed to markitdown — not configured by default.
Container runs on web_web-net so Caddy can resolve it by name.

2.1 KiB Raw Permalink Blame History