uitadmin/markitdown-api repository overview

⁠MarkItDown API - Docker Image

A production-ready FastAPI web service that converts files and URLs to Markdown using Microsoft's MarkItDown library with advanced image processing and intelligent hyperlink conversion capabilities.

Github repository: markitdown-api⁠

⁠🚀 Features

• File Upload & Conversion: Upload files directly and convert them to Markdown
• URL Conversion: Convert web pages and online documents to Markdown
• Multiple File Formats: PDF, Word documents, PowerPoint, Excel, images, HTML, and more
• Intelligent Hyperlink Conversion: Automatically converts embedded hyperlinks to proper Markdown format
• PDF Hyperlink Extraction: Extracts clickable links from PDF files using specialized libraries (PyMuPDF, PyPDF2, pdfplumber)
• Smart Link Detection: Avoids double-processing and nested bracket issues for clean link formatting
• Advanced Image Processing: Automatically extracts and integrates images from documents
• Smart Image Placement: Intelligently places extracted images within the markdown content
• Image URL Generation: Serves extracted images through accessible URLs
• Automated Image Cleanup: Scheduled daily cleanup of old image folders to manage disk space
• Configurable Retention: Customizable image retention period via environment variables
• Cleanup Monitoring: Real-time status monitoring of cleanup operations
• Secure Authentication: API key-based authentication for all conversion endpoints
• Production Security: Automatic documentation disabling in production environments
• Enterprise Ready: Optimized Docker image with health checks and monitoring
• High Performance: Multi-format support with efficient image processing
• Security Hardened: Non-root container execution with proper permissions

⁠🔗 Hyperlink Conversion Capabilities

⁠Advanced Link Processing

• Automatic PDF Link Extraction: Uses multiple specialized libraries to extract embedded hyperlinks from PDF files
• Manual Link Mapping: Comprehensive database covering classical literature, historical figures, and academic references
• Smart Text Processing: Converts plain text references to clickable Markdown links
• Multi-format Support: Works seamlessly with PDFs, Word documents, HTML files, and more
• Link Quality Assurance: Prevents nested brackets, malformed links, and double-processing

⁠🏗️ Container Optimizations

⁠Multi-Platform Support (as of v1.2.4)

• AMD64 Architecture: Full support for Intel/AMD 64-bit processors
• ARM64 Architecture: Native support for ARM-based processors (Apple Silicon, AWS Graviton, etc.)
• Cross-Platform Builds: Images built using Docker BuildX for maximum compatibility
• Universal Deployment: Single image works across different hardware architectures

⁠Production-Ready Build

• Python 3.11 Slim: Latest Python with minimal attack surface
• System Dependencies: Pre-installed libraries for image and PDF processing
• Layer Optimization: Efficient Docker layer caching for faster builds
• Size Optimized: Cleaned package caches and minimal base image

⁠Security Features

• Non-Root User: Runs as dedicated appuser for enhanced security
• Proper Permissions: Secure file system permissions and ownership
• Health Monitoring: Built-in health checks via /version endpoint
• Production Defaults: Secure environment settings out-of-the-box

⁠Performance Enhancements

• Optimized Builds: Platform-specific optimizations for both AMD64 and ARM64
• Image Processing Libraries: Pre-installed Pillow, PyMuPDF, python-docx
• Archive Support: Built-in support for ZIP, RAR, 7Z file extraction
• Memory Management: Optimized for containerized deployment
• Concurrent Processing: Handles multiple requests efficiently
• Background Scheduling: Automated cleanup runs independently without affecting API performance

⁠📋 Supported File Types

• PDF files (.pdf) - Full text extraction with cryptographic support + image extraction
• Microsoft Office: Word (.docx, .doc), PowerPoint (.pptx, .ppt), Excel (.xlsx, .xls) with embedded images
• Images with text: PNG, JPG, JPEG, GIF, BMP with OCR capabilities
• Web formats: HTML, HTM files with image references
• OpenDocument: ODF formats (.odt, .odp, .ods) with image support
• Archives: ZIP, RAR, 7Z files containing images
• Text formats: TXT, MD, and many more supported by MarkItDown

⁠🖼️ Image Processing Capabilities

⁠Automatic Image Extraction

• PDF Documents: Extracts all embedded images from every page
• Office Documents: Retrieves images from Word, PowerPoint, and Excel files
• Presentations: Extracts slide images and graphics
• Spreadsheets: Recovers embedded charts and images
• Archive Files: Finds and extracts images from compressed files

⁠Smart Integration

• Strategic Placement: Images appear after headings and at natural content breaks
• Content Flow: Maintains document structure and readability
• Dual Output: Images integrated in content + dedicated section for extras
• Accessible URLs: All images served through /images/ endpoint

⁠Example Output

# Document Title

Content here...

![image1.png](http://localhost:8000/images/document_abc123/image1.png)

## Section Header

More content...

![image2.png](http://localhost:8000/images/document_abc123/image2.png)

---

## Extracted Images

![image3.png](http://localhost:8000/images/document_abc123/image3.png)

⁠🧹 Automated Image Cleanup System

⁠Intelligent Disk Management

The container includes a sophisticated image cleanup system that automatically manages disk space by removing old extracted images while preserving recent ones for accessibility.

⁠Key Benefits

• Prevents Storage Bloat: Automatically removes old image folders to prevent unlimited disk growth
• Zero Maintenance: Runs completely in the background without manual intervention
• Production Ready: Designed for 24/7 operation in production environments
• Configurable: Fully customizable retention periods and cleanup schedules
• Monitoring: Complete visibility into cleanup operations and statistics

⁠Configuration Options

# Environment variables for image cleanup
IMAGE_CLEANUP_DAYS=7        # Delete folders older than 7 days (default)
IMAGE_CLEANUP_TIME=02:00    # Run cleanup daily at 2:00 AM (default)

⁠Common Configuration Examples

Conservative Cleanup (2 weeks retention)

echo "IMAGE_CLEANUP_DAYS=14" >> docker_apikeys.env
echo "IMAGE_CLEANUP_TIME=03:00" >> docker_apikeys.env

Aggressive Cleanup (3 days retention)

echo "IMAGE_CLEANUP_DAYS=3" >> docker_apikeys.env
echo "IMAGE_CLEANUP_TIME=01:30" >> docker_apikeys.env

Enterprise Setup

echo "IMAGE_CLEANUP_DAYS=10" >> docker_apikeys.env
echo "IMAGE_CLEANUP_TIME=02:00" >> docker_apikeys.env
echo "ENVIRONMENT=production" >> docker_apikeys.env

⁠Monitoring Cleanup Operations

Monitor the cleanup system using the /cleanup-status endpoint:

curl -H "Authorization: Bearer your-api-key" \
  http://localhost:8000/cleanup-status

Response includes:

• Current scheduler status
• Next cleanup time
• Retention configuration
• Images directory location

⁠🔧 Quick Start

⁠1. Create API Keys File

# Create your environment file with cleanup configuration
echo "API_KEYS=your-api-key-1,your-api-key-2" > docker_apikeys.env
echo "ENVIRONMENT=production" >> docker_apikeys.env
echo "MAX_UPLOAD_SIZE_MB=100" >> docker_apikeys.env
echo "IMAGE_CLEANUP_DAYS=7" >> docker_apikeys.env
echo "IMAGE_CLEANUP_TIME=02:00" >> docker_apikeys.env

⁠2. Run with Docker

# Latest version with automated cleanup
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/markitdown_images:/static/images \
  --env-file docker_apikeys.env \
  --name markitdown-api \
  --restart unless-stopped \
  markitdown/markitdown-api:latest

⁠3. Run with Docker Compose (Recommended)

version: '3.8'
services:
  markitdown-api:
    image: markitdown/markitdown-api:latest
    ports:
      - "8000:8000"
    env_file:
      - docker_apikeys.env
    volumes:
      - ./markitdown_images:/static/images  # Persist extracted images
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/version"]
      interval: 30s
      timeout: 10s
      retries: 3

⁠📊 Volume Management

⁠Persistent Storage

Mount volumes to persist extracted images and enable cleanup monitoring:

# Create directory for persistent image storage
mkdir -p markitdown_images
chmod 755 markitdown_images

# Run container with volume mounting
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/markitdown_images:/static/images \
  --env-file docker_apikeys.env \
  --name markitdown-api \
  markitdown/markitdown-api:latest

⁠Volume Benefits

• Data Persistence: Images survive container restarts
• Cleanup Visibility: See cleanup operations on host filesystem
• Backup Capability: Easy backup of extracted images
• Monitoring: Direct access to cleanup logs and statistics

⁠📚 API Endpoints

⁠Convert Files

POST /upload - Upload and convert files with automatic image processing

• Multi-format Support: PDF, Office docs, presentations, archives
• Image Integration: Extracts and places images intelligently in markdown
• Metadata Included: File size, image dimensions, accessible URLs
• Archive Processing: Handles ZIP, RAR, 7Z files with embedded images

⁠Convert URLs

POST /convert - Convert web pages and online documents

• Remote Processing: Downloads and processes files from URLs
• Image Handling: Processes images from remote documents
• Flexible Input: Supports direct file paths or HTTP/HTTPS URLs

⁠Image Access

GET /images/{folder}/{filename} - Direct access to extracted images

• Static Serving: High-performance image delivery
• Browser Compatible: Direct viewing and downloading
• Markdown Ready: URLs work seamlessly in markdown renderers

⁠Health & Monitoring

GET /version - API version and health status

• Container Health: Used by Docker health checks
• Version Tracking: Current API and library versions
• Uptime Monitoring: Integration with monitoring systems

⁠⚙️ Configuration

⁠Environment Variables

# Required
API_KEYS=key1,key2,key3

# Optional Production Settings
ENVIRONMENT=production          # Enable production security mode
MAX_UPLOAD_SIZE_MB=100         # File upload limit (default: 100MB)
DISABLE_DOCS=false             # Force disable API documentation

# Container Optimization
PYTHONUNBUFFERED=1             # Better logging in containers
PYTHONPATH=/app                # Proper Python path resolution

⁠Volume Mounting (Required for Image Processing)

# IMPORTANT: Create local directories with proper permissions first
mkdir -p ./static/images ./uploads

# Persist extracted images and uploads
docker run -d \
  -v $(pwd)/static:/app/static \
  -v $(pwd)/uploads:/app/uploads \
  -p 8000:8000 \
  --env-file docker_apikeys.env \
  --name markitdown-api \
  --restart unless-stopped \
  markitdown/markitdown-api:latest

Important Notes:

• Volume mounting is recommended to persist extracted images between container restarts
• Create directories first: Ensure ./static/images and ./uploads directories exist before running
• Permissions: The container runs as non-root user appuser for security
• Windows Users: Use %cd% instead of $(pwd) in PowerShell, or use Docker Desktop with relative paths

⁠Windows-Specific Instructions

# PowerShell - Create directories and run container
New-Item -ItemType Directory -Force -Path ".\static\images", ".\uploads"
docker run -d `
  -v "${PWD}/static:/app/static" `
  -v "${PWD}/uploads:/app/uploads" `
  -p 8000:8000 `
  --env-file docker_apikeys.env `
  --name markitdown-api `
  --restart unless-stopped `
  markitdown/markitdown-api:latest

⁠Resource Limits

# Production deployment with resource constraints
docker run -d \
  --memory=1g \
  --cpus=0.5 \
  --restart=unless-stopped \
  -p 8000:8000 \
  --env-file docker_apikeys.env \
  markitdown/markitdown-api:latest

⁠🔒 Security & Compliance

⁠Container Security

• Non-Root Execution: Runs as unprivileged user appuser
• Minimal Base Image: Python 3.11 slim reduces attack surface
• No Unnecessary Packages: Clean image without development tools
• Health Monitoring: Continuous health status reporting

⁠API Security

• Authentication Required: All conversion endpoints require valid API keys
• Production Mode: Automatically disables documentation in production
• File Size Limits: Configurable upload limits prevent resource abuse
• Secure Headers: Production-ready security configurations

⁠Data Handling

• Temporary File Cleanup: Automatic cleanup of processed files
• Isolated Processing: Each request processed in isolation
• Configurable Persistence: Optional volume mounting for image persistence
• Memory Management: Efficient handling of large documents

⁠📊 Response Format

Enhanced response includes integrated images:

{
  "filename": "presentation.pptx",
  "content": "# Quarterly Report\n\n![chart1.png](http://localhost:8000/images/presentation_abc123/chart1.png)\n\n## Overview\n\nContent here...\n\n![diagram.png](http://localhost:8000/images/presentation_abc123/diagram.png)\n\n---\n\n## Extracted Images\n\n![logo.png](http://localhost:8000/images/presentation_abc123/logo.png)",
  "images": [
    {
      "filename": "chart1.png",
      "url": "http://localhost:8000/images/presentation_abc123/chart1.png",
      "width": 1024,
      "height": 768
    },
    {
      "filename": "diagram.png", 
      "url": "http://localhost:8000/images/presentation_abc123/diagram.png",
      "width": 800,
      "height": 600
    },
    {
      "filename": "logo.png",
      "url": "http://localhost:8000/images/presentation_abc123/logo.png", 
      "width": 200,
      "height": 100
    }
  ],
  "file_size": 2048576
}

⁠🚀 Performance & Scaling

⁠Resource Efficiency

• Optimized Dependencies: Only essential libraries included
• Memory Management: Efficient cleanup and garbage collection
• Concurrent Processing: Handles multiple requests simultaneously
• Fast Startup: Optimized container initialization

⁠Scaling Recommendations

# Docker Swarm deployment
services:
  markitdown-api:
    image: markitdown/markitdown-api:latest
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
      resources:
        limits:
          memory: 1G
          cpus: '0.5'
    ports:
      - "8000:8000"
    env_file:
      - docker_apikeys.env

⁠Monitoring Integration

• Health Endpoints: Built-in health checks for orchestration
• Structured Logging: Container-friendly log output
• Metrics Ready: Compatible with monitoring solutions
• Graceful Shutdown: Proper signal handling for rolling updates

⁠📝 Use Cases

⁠Enterprise Document Processing

• Batch Conversion: Convert large document repositories
• Visual Content Preservation: Maintain charts, diagrams, and images
• Multi-format Support: Handle diverse document types in one solution
• API Integration: Seamless integration with existing workflows

⁠Content Management Systems

• Document Migration: Convert legacy documents to markdown
• Image Preservation: Maintain visual elements during migration
• Automated Processing: Bulk processing with consistent results
• Web Integration: Direct integration with web applications

⁠Documentation Workflows

• Technical Documentation: Convert presentations to markdown docs
• Knowledge Base: Transform varied formats to unified markdown
• Archive Processing: Extract content from compressed document archives
• Version Control: Markdown output ready for Git-based workflows

⁠🏷️ Available Tags

• latest - Latest stable release with all features
• v1.2.0 - Specific version with enhanced image processing
• production - Production-optimized build (coming soon)

⁠🔗 Links

• GitHub Repository: markitdown-api⁠
• Docker Hub: uitadmin/markitdown-api⁠
• API Documentation: Available at /docs (development mode)
• Microsoft MarkItDown: Official Library⁠
• Issues & Support: GitHub Issues⁠

⁠📄 License

MIT License - See repository for full license text.