# pdf2md

[![PyPI version](https://badge.fury.io/py/pdf2md.svg)](https://badge.fury.io/py/pdf2md)
[![Python](https://img.shields.io/pypi/pyversions/pdf2md.svg)](https://pypi.org/project/pdf2md/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Converts PDF files to Markdown using the Gemini API.

## Installation

### From PyPI (Recommended)

```bash
pip install pdf2md
```

For pre-release versions:
```bash
pip install --pre pdf2md
```

### From Source

```bash
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
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:

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

## Usage

Direct script usage:

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

Installed command usage:

```bash
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

```bash
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:

```bash
export MY_GEMINI_API_KEY="your_api_key_here"
```

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

```bash
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](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](https://github.com/marcbadiam/pdf2md/issues) on GitHub.
