# MarkItDown

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

Built with FastAPI + [markitdown](https://github.com/microsoft/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

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

---

## Deploy

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

Caddy block in `/opt/web/Caddyfile`:

```caddy
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.