{"id":27232858,"url":"https://github.com/jarus77/markdrop","last_synced_at":"2026-04-13T22:31:25.221Z","repository":{"id":286280815,"uuid":"960945633","full_name":"Jarus77/markdrop","owner":"Jarus77","description":" A Python package for converting PDFs to markdown while extracting images and tables, generate descriptive text descriptions for extracted tables/images using several LLM clients. And many more functionalities. Markdrop is available on PyPI.","archived":false,"fork":false,"pushed_at":"2025-04-05T12:17:16.000Z","size":88,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T13:24:59.389Z","etag":null,"topics":["agents","docling","image-to-text","llm","markdown","markdrop","marker","opensource","pdf-to-markdown","pdf-to-te","pypi-package","table-to-text"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/markdrop/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jarus77.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-05T12:15:28.000Z","updated_at":"2025-04-05T12:20:35.000Z","dependencies_parsed_at":"2025-04-05T13:25:01.751Z","dependency_job_id":"00724a89-d622-4981-8120-4698cd88e864","html_url":"https://github.com/Jarus77/markdrop","commit_stats":null,"previous_names":["jarus77/markdrop"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jarus77%2Fmarkdrop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jarus77%2Fmarkdrop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jarus77%2Fmarkdrop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jarus77%2Fmarkdrop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jarus77","download_url":"https://codeload.github.com/Jarus77/markdrop/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248232319,"owners_count":21069487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","docling","image-to-text","llm","markdown","markdrop","marker","opensource","pdf-to-markdown","pdf-to-te","pypi-package","table-to-text"],"created_at":"2025-04-10T14:10:14.277Z","updated_at":"2026-04-13T22:31:25.180Z","avatar_url":"https://github.com/Jarus77.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"left\"\u003e\n  \u003cimg src=\"https://github.com/shoryasethia/markdrop/blob/main/markdrop/src/markdrop-logo.png\" alt=\"Markdrop Logo\" width=\"200\" height=\"200\"/\u003e\n  \u003ch1 style=\"display: inline; font-size: 2em; vertical-align: middle; padding-left: 10px; margin: 0;\"\u003e\u003ca href = \"https://github.com/shoryasethia/markdrop\"\u003eMarkdrop\u003c/a\u003e\u003c/h1\u003e\n\u003c/p\u003e\n\n[![Downloads](https://static.pepy.tech/badge/markdrop)](https://pepy.tech/projects/markdrop)\n[![PyPI Version](https://img.shields.io/pypi/v/markdrop)](https://pypi.org/project/markdrop/)\n[![License](https://img.shields.io/github/license/shoryasethia/markdrop)](https://github.com/shoryasethia/markdrop/blob/main/LICENSE)\n[![Stars](https://img.shields.io/github/stars/shoryasethia/markdrop?style=social)](https://github.com/shoryasethia/markdrop/stargazers)\n[![Issues](https://img.shields.io/github/issues/shoryasethia/markdrop)](https://github.com/shoryasethia/markdrop/issues)\n[![Forks](https://img.shields.io/github/forks/shoryasethia/markdrop?style=social)](https://github.com/shoryasethia/markdrop/network/members)\n\u003ca href=\"https://www.producthunt.com/posts/markdrop?embed=true\u0026utm_source=badge-featured\u0026utm_medium=badge\u0026utm_souce=badge-markdrop\" target=\"_blank\"\u003e\u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=919009\u0026theme=dark\u0026t=1740746408634\" alt=\"Markdrop - PDF\u0026#0032;to\u0026#0032;markdown\u0026#0032;\u0026#0124;\u0026#0032;Tables\u0026#0032;to\u0026#0032;Excel\u0026#0032;\u0026#0124;\u0026#0032;Table\u0026#0047;Images\u0026#0032;Description | Product Hunt\" style=\"width: 105px; height: px;\"  /\u003e\u003c/a\u003e\n\nA Python package for converting PDFs to markdown while extracting images and tables, generate descriptive text descriptions for extracted tables/images using several LLM clients. And many more functionalities. Markdrop is available on PyPI.\n\n## Quick Start  \n\n[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1oApTrP_kjNn0s1tpE0SIWRyGzYfflQsi?usp=sharing)\n[![Watch the demo](https://img.shields.io/badge/YouTube-Demo-red?logo=youtube\u0026logoColor=white)](https://youtu.be/2xg7W0-oiw0)\n\n## Features  \n\n- [x] PDF to Markdown conversion with formatting preservation using Docling\n- [x] Automatic image extraction with quality preservation using XRef Id\n- [x] Table detection using Microsoft's Table Transformer\n- [x] PDF URL support for core functionalities\n- [x] AI-powered image and table descriptions using multiple LLM providers\n- [x] Interactive HTML output with downloadable Excel tables\n- [x] Customizable image resolution and UI elements\n- [x] Comprehensive logging system\n- [ ] Support for other files\n- [ ] Streamlit/web interface\n\n## Installation  \n\n```bash  \npip install markdrop  \n```  \n\n#### Python Package Index (PyPI) Page: https://pypi.org/project/markdrop\n\n### Basic PDF Processing\n\n```python\nfrom markdrop import extract_images, make_markdown, extract_tables_from_pdf\n\nsource_pdf = 'url/or/path/to/pdf/file'    # Replace with your local PDF file path or a URL\noutput_dir = 'data/output'                 # Replace with desired output directory's path\n\nmake_markdown(source_pdf, output_dir)\nextract_images(source_pdf, output_dir)\nextract_tables_from_pdf(source_pdf, output_dir=output_dir)\n```\n\n### Advanced PDF Processing with MarkDrop\n\n```python\nfrom markdrop import markdrop, MarkDropConfig, add_downloadable_tables\nfrom pathlib import Path\nimport logging\n\n# Configure processing options\nconfig = MarkDropConfig(\n    image_resolution_scale=2.0,        # Scale factor for image resolution\n    download_button_color='#444444',   # Color for download buttons in HTML\n    log_level=logging.INFO,           # Logging detail level\n    log_dir='logs',                   # Directory for log files\n    excel_dir='markdropped-excel-tables'  # Directory for Excel table exports\n)\n\n# Process PDF document\ninput_doc_path = \"path/to/input.pdf\"\noutput_dir = Path('output_directory')\n\n# Convert PDF and generate HTML with images and tables\nhtml_path = markdrop(input_doc_path, output_dir, config)\n\n# Add interactive table download functionality\ndownloadable_html = add_downloadable_tables(html_path, config)\n```\n\n### AI-Powered Content Analysis\n\n```python\nfrom markdrop import setup_keys, process_markdown, ProcessorConfig, AIProvider, logger\nfrom pathlib import Path\n\n# Set up API keys for AI providers\nsetup_apikeys(key='gemini')  # or setup_keys(key='openai')\n\n# Configure AI processing options\nconfig = ProcessorConfig(\n    input_path=\"path/to/markdown/file.md\",    # Input markdown file path\n    output_dir=Path(\"output_directory\"),      # Output directory\n    ai_provider=AIProvider.GEMINI,            # AI provider (GEMINI or OPENAI)\n    remove_images=False,                      # Keep or remove original images\n    remove_tables=False,                      # Keep or remove original tables\n    table_descriptions=True,                  # Generate table descriptions\n    image_descriptions=True,                  # Generate image descriptions\n    max_retries=3,                           # Number of API call retries\n    retry_delay=2,                           # Delay between retries in seconds\n    gemini_model_name=\"gemini-1.5-flash\",    # Gemini model for images\n    gemini_text_model_name=\"gemini-pro\",     # Gemini model for text\n    image_prompt=DEFAULT_IMAGE_PROMPT,        # Custom prompt for image analysis\n    table_prompt=DEFAULT_TABLE_PROMPT         # Custom prompt for table analysis\n)\n\n# Process markdown with AI descriptions\noutput_path = process_markdown(config)\n```\n\n### Image Description Generation\n\n```python\nfrom markdrop import generate_descriptions\n\nprompt = \"Give textual highly detailed descriptions from this image ONLY, nothing else.\"\ninput_path = 'path/to/img_file/or/dir'\noutput_dir = 'data/output'\nllm_clients = ['gemini', 'llama-vision']  # Available: ['qwen', 'gemini', 'openai', 'llama-vision', 'molmo', 'pixtral']\n\ngenerate_descriptions(\n    input_path=input_path,\n    output_dir=output_dir,\n    prompt=prompt,\n    llm_client=llm_clients\n)\n```\n\n## API Reference  \n\n### Core Functions\n\n#### markdrop(input_doc_path: str, output_dir: str, config: Optional[MarkDropConfig] = None) -\u003e Path\nConverts PDF to markdown and HTML with enhanced features.\n\nParameters:\n- `input_doc_path` (str): Path to input PDF file\n- `output_dir` (str): Output directory path\n- `config` (MarkDropConfig, optional): Configuration options for processing\n\n#### add_downloadable_tables(html_path: Path, config: Optional[MarkDropConfig] = None) -\u003e Path\nAdds interactive table download functionality to HTML output.\n\nParameters:\n- `html_path` (Path): Path to HTML file\n- `config` (MarkDropConfig, optional): Configuration options\n\n### Configuration Classes\n\n#### MarkDropConfig\nConfiguration for PDF processing:\n- `image_resolution_scale` (float): Scale factor for image resolution (default: 2.0)\n- `download_button_color` (str): HTML color code for download buttons (default: '#444444')\n- `log_level` (int): Logging level (default: logging.INFO)\n- `log_dir` (str): Directory for log files (default: 'logs')\n- `excel_dir` (str): Directory for Excel table exports (default: 'markdropped-excel-tables')\n\n#### ProcessorConfig\nConfiguration for AI processing:\n- `input_path` (str): Path to markdown file\n- `output_dir` (str): Output directory path\n- `ai_provider` (AIProvider): AI provider selection (GEMINI or OPENAI)\n- `remove_images` (bool): Whether to remove original images\n- `remove_tables` (bool): Whether to remove original tables\n- `table_descriptions` (bool): Generate table descriptions\n- `image_descriptions` (bool): Generate image descriptions\n- `max_retries` (int): Maximum API call retries\n- `retry_delay` (int): Delay between retries in seconds\n- `gemini_model_name` (str): Gemini model for image processing\n- `gemini_text_model_name` (str): Gemini model for text processing\n- `image_prompt` (str): Custom prompt for image analysis\n- `table_prompt` (str): Custom prompt for table analysis\n\n### Legacy Functions\n\n#### make_markdown(source: str, output_dir: str, verbose: bool = False)\nLegacy function for basic PDF to markdown conversion.\n\nParameters:\n- `source` (str): Path to input PDF or URL\n- `output_dir` (str): Output directory path\n- `verbose` (bool): Enable detailed logging\n\n#### extract_images(source: str, output_dir: str, verbose: bool = False)\nLegacy function for basic image extraction.\n\nParameters:\n- `source` (str): Path to input PDF or URL\n- `output_dir` (str): Output directory path\n- `verbose` (bool): Enable detailed logging\n\n#### extract_tables_from_pdf(pdf_path: str, **kwargs)\nLegacy function for basic table extraction.\n\nParameters:\n- `pdf_path` (str): Path to input PDF or URL\n- `start_page` (int, optional): Starting page number\n- `end_page` (int, optional): Ending page number\n- `threshold` (float, optional): Detection confidence threshold\n- `output_dir` (str): Output directory path\n\n### Quick Start for Legacy Functions\nCheck an example in [`run.py`](https://github.com/shoryasethia/markdrop/blob/main/markdrop/run.py)\n\n## Contributing  \n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.  \n\n### Development Setup  \n\n1. Clone the repository:  \n```bash  \ngit clone https://github.com/shoryasethia/markdrop.git  \ncd markdrop  \n```  \n\n2. Create a virtual environment:  \n```bash  \npython -m venv venv  \nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate  \n```  \n\n3. Install development dependencies:  \n```bash  \npip install -r requirements.txt  \n```  \n\n## Project Structure  \n\n```bash  \nmarkdrop/  \n├── LICENSE  \n├── README.md  \n├── CONTRIBUTING.md  \n├── CHANGELOG.md  \n├── requirements.txt  \n├── setup.py  \n└── markdrop/ \n    ├── __init__.py \n    ├── src\n    |    └── markdrop-logo.png\n    ├── main.py\n    ├── process.py\n    ├── api_setup.py\n    ├── parse.py\n    ├── utils.py  \n    ├── helper.py\n    ├── ignore_warnings.py\n    ├── run.py\n    └── models/\n        ├── __init__.py\n        ├── .env\n        ├── img_descriptions.py\n        ├── logger.py\n        ├── model_loader.py\n        ├── responder.py\n        └── setup_keys.py  \n```  \n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=shoryasethia/markdrop\u0026type=Timeline)](https://star-history.com/#shoryasethia/markdrop\u0026Timeline)\n\n## License  \n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.  \n\n## Changelog  \n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.  \n\n## Code of Conduct  \n\nPlease note that this project follows our [Code of Conduct](CODE_OF_CONDUCT.md).  \n\n## Support  \n\n- [Open an issue](https://github.com/shoryasethia/markdrop/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarus77%2Fmarkdrop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjarus77%2Fmarkdrop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarus77%2Fmarkdrop/lists"}