pdf2md

Converts PDF files to Markdown using the Gemini API.

Installation

From PyPI (Recommended)

pip install pdf2md

For pre-release versions:

pip install --pre pdf2md

From Source

git clone https://github.com/marcbadiam/pdf2md.git
cd pdf2md
pip install -e .

Project Files

• pdf2md.py: Main conversion script.
• setup.sh: Setup helper for API key configuration and command installation.

Dependencies

System dependencies:

• Python 3.8 or later.
• Bash.
• Coreutils (install command).
• Internet access to call the Gemini API.

Installation

1. Enter the project directory.
2. Run the setup script:

bash setup.sh

The setup.sh script:

• Prompts for the API key in the terminal.
• Stores MY_GEMINI_API_KEY in the active shell rc file.
• Installs the pdf2md command in /usr/local/bin if writable.
• Falls back to ~/.local/bin when /usr/local/bin is not writable.

If installation uses ~/.local/bin and it is not in PATH, add this line to your rc file:

export PATH="$HOME/.local/bin:$PATH"

Usage

Direct script usage:

python3 pdf2md.py <input.pdf> [output.md]

Installed command usage:

pdf2md <input.pdf> [output.md]

Behavior:

• input.pdf: Input PDF file path.
• output.md: Optional output file path. If omitted, the script uses the input filename with .md.

Examples

python3 pdf2md.py document.pdf
python3 pdf2md.py document.pdf output.md
pdf2md document.pdf
pdf2md document.pdf output.md

Configuration

Set your Gemini API key as an environment variable:

export MY_GEMINI_API_KEY="your_api_key_here"

For permanent configuration, add it to your shell rc file (~/.bashrc, ~/.zshrc, etc.):

echo 'export MY_GEMINI_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

Notes

• MY_GEMINI_API_KEY must be set for API requests to work.
• Open a new terminal or reload your shell session after rc file changes.

Features

• 📄 PDF to Markdown conversion using Google Gemini API
• 🔍 Advanced OCR with support for complex layouts
• 📊 Table detection and formatting
• 🔢 Mathematical formulas rendered in LaTeX
• 💻 Code block detection with syntax highlighting
• 🖼️ Image handling with transcription and descriptions
• 🌍 Multi-language support preserves original document language

Requirements

• Python 3.8 or higher
• Google Gemini API key
• Internet connection

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on GitHub.