Markdownify

Mardownify is a super easy-to-use PDF/image to high-quality Markdown converter using Vision LLMs. It supports text, images, signatures, tables, charts, flowcharts and preserves document structure (Headings, numbered lists etc).

Tables become Markdown tables, charts become Mermaid diagrams, and images get concise summaries. Use as a CLI or Python library. Works with 100+ LLMs. Recommended to use with gpt-5-mini or gpt-4.1-mini or even better models for better performance. The best part is you have complete control over what gets rendered how!

If you don't believe it there's a whole gallery of examples with really wide range of OCR tasks you can explore here -> Gallery

Install

uv pip install llm-markdownify
# or
pip install llm-markdownify

Quickstart (CLI)

# Set OpenAI key as env var
export OPENAI_API_KEY="sk-.."
# PDF input
markdownify input.pdf -o output.md --model gpt-5-mini

# Or single image input (PNG/JPG/JPEG)
markdownify input.png -o output.md --model gpt-5-mini

Features

• High-quality complex markdown generation powered by LLMs.
• Supports Text, Images, Tables, Charts.
• Built-in prompts tuned for clean Markdown, Mermaid, and structured headings along with ability to customise.
• Supports multi-page tables, charts and images.
• High-fidelity page rendering from PDF.
• Optional DOCX→PDF conversion using MS word installation.
• Works seamlessly with 100+ LLMs with LiteLLM Intergration.

Python API (one-liner)

from llm_markdownify import convert

convert(
    "input.pdf",  # or an image path like "input.png"
    "output.md",
    model="gpt-5-mini",   # optional; can rely on env/provider defaults
    dpi=72,
    profile="contracts",    # or path to JSON profile
)

Optional DOCX support (macOS/Windows via Word):

pip install llm-markdownify[docx]

Configure your provider (via LiteLLM)

Pick one of the following. See the full providers list and details in the LiteLLM docs: Supported Providers.

• OpenAI

  • Set your API key:

    export OPENAI_API_KEY="sk-..."

  • Example usage:

    markdownify input.pdf -o output.md --model gpt-5-mini

• Google Gemini

  • Set your API key (Google AI Studio key):

    export GEMINI_API_KEY="..."

  • Example usage (pick a Gemini vision-capable model):

    markdownify input.pdf -o output.md --model gemini/gemini-2.5-flash

• OpenRouter

  • Set your API key (OpenRouter API Key):

    export OPENROUTER_API_KEY="..."

  • Example usage (pick a Gemini vision-capable model):

    markdownify input.pdf -o output.md --model openrouter/z-ai/glm-4.5v

• Azure OpenAI

  • Set these environment variables (values from your Azure OpenAI resource):

    export AZURE_API_KEY="..."
    export AZURE_API_BASE="https://<your-resource>.openai.azure.com"
    export AZURE_API_VERSION=""

  • Use your deployment name via the azure/<deployment_name> model syntax:

    markdownify input.pdf -o output.md --model azure/<deployment_name>

  • See: LiteLLM Azure OpenAI

• OpenAI-compatible APIs

  • Many providers expose an OpenAI-compatible REST API. Set your API key and base URL:

    export OPENAI_API_KEY="..."
    export OPENAI_API_BASE="https://your-openai-compatible-endpoint.com/v1"

  • Use the model name supported by that endpoint:

    markdownify input.pdf -o output.md --model <model-name>

  • Reference: LiteLLM Providers

For additional providers and advanced configuration (fallbacks, cost tracking, streaming), see the LiteLLM docs: Getting Started.

Configuration flags

• --model: LiteLLM model (e.g., gpt-5-mini, azure/<deployment>, gemini/gemini-2.5-flash)
• --dpi: Render DPI (default 72). Ignored for direct image inputs.
• --max-group-pages: Max pages to merge for continued content (default 3)
• --no-grouping: Disable LLM-based grouping
• --temperature, --max-tokens: LLM generation params
• --grouping_concurrency : to control how many checks are made at once (defaults to concurrency)

Markdownify Cloud

If you’d like to run Markdownify in production with advanced features, on your own infrastructure, using your own LLMs, or tailored to your specific use case, visit markdownify.xyz to explore our cloud offering and get in touch.

Markdownify Cloud gives you access to better version of Markdownify that gives better results than the open-source version, with additional features and hands-on support to help you integrate it into your workflow.

Attribution & License

This project uses the Apache 2.0 License, which includes an attribution/NOTICE requirement. If you distribute or use this project, please keep the LICENSE and NOTICE files intact, crediting the original author, Sethu Pavan Venkata Reddy Pastula.

• Project repository: https://github.com/sethupavan12/Markdownify

Development

• Requires Python 3.10+
• Use uv for fast installs: uv sync
• Run tests: pytest
• Lint: ruff check src tests

Check CONTRIBUTING.md for more details

Releasing

GitHub Actions are configured to:

• Run tests on PRs/pushes
• Build & publish to PyPI on tagged releases