A beautiful web-based console dashboard and local API proxy service for Microsoft's MarkItDown document converter library. Convert PDFs, Word, PowerPoint, Excel, Images (with OCR), Audio (transcription), EPubs, HTML pages, ZIPs, and YouTube links into Markdown.
Built with clean, premium custom CSS (dark-theme console style) and vanilla JavaScript, supporting multi-file queues, inline prerequisite validation, and multiple credentials management modes.
If you find this project useful, please consider giving it a star on GitHub! It helps other developers discover the project and keeps development active.
- Multi-File Queue: Drag and drop multiple files to convert them sequentially. Individual cards show conversion progress (
converting,done,error) and allow dismissing items. - Context-Aware Visual Input: Drop zones automatically disable when using URL-only presets (like YouTube).
- Pre-flight Format Validation: Supported format badges and file chooser dialog filters update dynamically based on the chosen preset. Incompatible uploads are blocked immediately (both in UI and backend API).
- Robust YouTube Transcripts: Utilizes
yt-dlpsubtitle track analysis to bypass timedtext extraction limits and PoToken/signature restrictions, with automatic fallback for auto-generated captions. - Offline Preview: Offline markdown rendering using bundled
marked.min.js.
To suit both open-source localhost setups and shared web deployments, MarkItDown UI supports two methods for managing API credentials:
- Use Case: Local developer installations.
- How it works: Enter your API key (e.g. OpenAI or Azure) in the UI Settings. The frontend derives a key using PBKDF2 from a master passphrase and encrypts your keys using authenticated AES-GCM before saving them in
localStorage. - Security: Keys are decrypted in-memory only. They never touch the server disk in plaintext.
- Use Case: Deploying on a server or shared Docker infrastructure.
- How it works: Set API credentials in the server's
.envconfiguration file. The backend reads these at startup. - Security: The browser never sees, requests, or stores these keys. The frontend dynamically detects their presence on the server and bypasses key prompt fields automatically.
This project uses uv, a fast Python package and project manager.
- macOS/Linux:
uvwill be installed automatically by the setup script if not found. - Windows:
uvwill be installed automatically by the setup batch script if not found. - Python: Python 3.10+ is required on the system.
# 1. Install dependencies (creates .venv and downloads assets using uv)
chmod +x scripts/*.sh
./scripts/install.sh
# 2. Run the application (starts local server using uv run)
./scripts/start.sh:: 1. Install dependencies
scripts\install.bat
:: 2. Run the application
scripts\start.batWe provide Docker files to easily package and run the application. System dependencies (such as ffmpeg for speech transcription) are pre-bundled in the container.
Copy the template file to .env and fill in any keys:
cp .env.example .envUse the wrapper script:
chmod +x scripts/docker-build.sh
./scripts/docker-build.shOr run directly:
docker compose up -d --buildThe application will be accessible at: http://localhost:7432
The production compose setups binds the application behind an Nginx container serving SSL:
- Place your SSL certificate and key files in
./nginx/certs/cert.pemand./nginx/certs/key.pem. - Launch the production compose:
docker compose -f docker-compose.prod.yml up -d --build
You can customize the host and port in two places:
- Local Native Run: Edit
config.jsonin the root directory. - Docker Compose Run: Edit
PORTin the.envfile.
This project is licensed under the Apache License 2.0. See the LICENSE file for the full license text.