docs: add README

2026-05-28 12:02:30 +00:00
parent 491b525822
commit 9693fc20e4
1 changed files with 93 additions and 0 deletions
@@ -0,0 +1,93 @@
+# 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.