llm-markdownify 0.1.0

Convert documents (PDF, DOCX) to high-quality Markdown using Vision LLMs via LiteLLM

Markdownify

Mardownify is a super easy-to-use PDF 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.

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.

Install

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

Quickstart (CLI)

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

Python API (one-liner)

from llm_markdownify import convert

convert(
    "input.pdf",
    "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 run input.pdf -o output.md --model gpt-5-mini
    

• Google Gemini

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

    export GOOGLE_API_KEY="..."
    

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

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

• 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 run 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 run 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)
• --max-group-pages: Max pages to merge for continued content (default 3)
• --no-grouping: Disable LLM-based grouping
• --temperature, --max-tokens: LLM generation params

Dev tooling

• Install pre-commit and enable the license header hook:

  pip install pre-commit
  pre-commit install
  # run on all files once
  pre-commit run --all-files
  

  This inserts the header:

  # Copyright (c) 2025 Sethu Pavan Venkata Reddy Pastula
  # Licensed under the Apache License, Version 2.0. See LICENSE file for details.
  # SPDX-License-Identifier: Apache-2.0
  

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

Releasing

GitHub Actions are configured to:

• Run tests on PRs/pushes
• Build & publish to PyPI on tagged releases (requires PYPI_API_TOKEN secret)