Skip to content
Back to search

markdrop

SkillWorks with Claude CodeGitHub

Professional AI skill and usage instructions for the Markdrop package, a Python tool for converting PDFs to Markdown/HTML with AI-powered image/table descriptions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shoryasethia--markdrop/badge.svg)](/listings/shoryasethia--markdrop)

HTML

<a href="/listings/shoryasethia--markdrop"><img src="/api/listings/shoryasethia--markdrop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Core install (PDF conversion + Gemini/OpenAI):**

pip install markdrop

**With Anthropic Claude:**

pip install "markdrop[anthropic]"

**With Groq:**

pip install "markdrop[groq]"

**With LiteLLM (routes to 100+ providers):**

pip install "markdrop[litellm]"

**Everything (including local HuggingFace models):**

pip install "markdrop[all]"

**Faster CPU / lightweight Markdown (`--fast` mode):**

pip install "markdrop[lite]"
markdrop convert report.pdf --output_dir out --fast

See [docs/cpu-guide.md](docs/cpu-guide.md) for CPU-only and Colab guidance.

> **OpenRouter** is accessed through the `openai` package (already included in core), so no extra install is needed.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 136 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: markdrop
  3. description: Professional AI skill and usage instructions for the Markdrop package, a Python tool for converting PDFs to Markdown/HTML with AI-powered image/table descriptions.
  4. ---
  5. # Markdrop Skill
  6. Welcome to the `markdrop` skill. `markdrop` is a powerful Python package and CLI tool used to convert PDF documents into structured Markdown and interactive HTML, while natively leveraging AI vision models to interpret and describe extracted images and tables.
  7. If you are an AI agent or a user aiming to process PDFs and augment them with text or image descriptions, this document serves as your complete guide on utilizing `markdrop` efficiently and accurately.
  8. ## 1. Capabilities
  9. - **PDF to Markdown/HTML**: Retains formatting, extracts images, and detects tables via Microsoft Table Transformer and Docling. Supports processing both local file paths and direct PDF URLs.
  10. - **AI Vision Descriptions**: Query GEMINI, OPENAI, ANTHROPIC, GROQ, OPENROUTER, or LITELLM to generate rich descriptions of images and tables.
  11. - **Batch Processing**: Describe entire directories of images in single commands using multiple LLM backends simultaneously.
  12. - **Extensible Configuration**: Precise override control over which structural text-models vs vision-models are used, as well as prompts, resolution scales, and output features.
  13. ## 2. API Keys Setup
  14. Before using AI features, API keys must be available in the root `.env` file or environment variables.
  15. If deploying programmatically, you can run the built-in CLI command, or inject them into `os.environ`:
  16. ```bash
  17. markdrop setup gemini # -> GEMINI_API_KEY
  18. markdrop setup openai # -> OPENAI_API_KEY
  19. markdrop setup anthropic # -> ANTHROPIC_API_KEY
  20. markdrop setup groq # -> GROQ_API_KEY
  21. markdrop setup openrouter # -> OPENROUTER_API_KEY
  22. markdrop setup litellm # -> LITELLM_API_KEY
  23. ```
  24. ## 3. Python API Integration
  25. The Python API is the recommended way to embed `markdrop` into applications.
  26. ### 3.1 PDF Conversion to Interactive HTML
  27. Use `markdrop` function combined with `add_downloadable_tables`:
  28. ```python
  29. from markdrop import markdrop, MarkDropConfig, add_downloadable_tables
  30. from pathlib import Path
  31. import logging
  32. # Configuration block
  33. config = MarkDropConfig(
  34. image_resolution_scale=2.0,
  35. download_button_color="#444444",
  36. log_level=logging.INFO,
  37. log_dir="logs",
  38. excel_dir="markdrop-excel-tables",
  39. )
  40. # 1. Convert PDF to base HTML (and markdown locally). URL supported here too: "https://url.to/pdf"
  41. html_path = markdrop("path/to/document.pdf", "output_directory", config)
  42. # 2. Enrich HTML to allow downloading tables as Excel sheets
  43. enhanced_html_path = add_downloadable_tables(html_path, config)
  44. ```
  45. ### 3.2 Injecting AI Descriptions into Markdown
  46. If you have a Markdown file containing image/table links, `process_markdown` automatically routes vision requests to the chosen provider and inserts contextual descriptions.
  47. ```python
  48. from markdrop import process_markdown, ProcessorConfig, AIProvider
  49. config = ProcessorConfig(
  50. input_path="output_directory/document.md",
  51. output_dir="output_directory",
  52. ai_provider=AIProvider.GEMINI, # Available: GEMINI, OPENAI, ANTHROPIC, GROQ, OPENROUTER, LITELLM
  53. # Target configurations
  54. remove_images=False,
  55. remove_tables=False,
  56. table_descriptions=True,
  57. image_descriptions=True,
  58. # Provider-Specific overrides (Optional)
  59. # Allows granular decoupling of vision parsing vs table text-parsing
  60. model_name_override="gemini-2.0-flash", # Primary vision analysis model
  61. text_model_name_override="gemini-2.0-flash", # Lean text-only model for generic parsing
  62. )
  63. # Executes AI processing and saves the enriched document
  64. output_path = process_markdown(config)
  65. ```
  66. ### 3.3 Batch Image Description
  67. For standalone image directories or files:
  68. ```python
  69. from markdrop import generate_descriptions
  70. generate_descriptions(
  71. input_path="images_folder/",
  72. output_dir="descriptions_output/",
  73. prompt="Analyze this image and describe all textual and structural elements.",
  74. llm_client=["gemini", "openai"],
  75. )
  76. ```
  77. ## 4. CLI Execution Best Practices
  78. As an agent, you can also trigger `markdrop` workflows via Bash.
  79. 1. **Convert PDF to MD/HTML (including tables)**:
  80. ```bash
  81. markdrop convert <input_path_or_url> --output_dir <dir> --add_tables
  82. ```
  83. 2. **Run AI Provider over the Markdown Output with exact models**:
  84. ```bash
  85. markdrop describe <markdown_file> \
  86. --ai_provider anthropic \
  87. --model claude-opus-4-6 \
  88. --text-model claude-sonnet-4-5 \
  89. --remove_images
  90. ```
  91. 3. **Only Analyze / Extract Images**:
  92. ```bash
  93. # Also accepts URLs directly
  94. markdrop analyze https://domain.com/report.pdf --output_dir pdf_analysis --save_images
  95. ```
  96. 4. **Batch Image Description**:
  97. ```bash
  98. markdrop generate images/ --output_dir descriptions/ \
  99. --prompt "Describe in detail." \
  100. --llm_client gemini openai
  101. ```
  102. ## 5. Typical Model Fallbacks & Suggestions
  103. - **Default / Cost-Effective**: `gemini` (Gemini 2.0 Flash) is frequently the fastest and cheapest for large scale document evaluation.
  104. - **High Complexity / Intricate Tables**: `anthropic` with the latest Claude models (`claude-opus-4-6` or `claude-sonnet-4-5`) excel in reasoning and formatting.
  105. - **Maximum Speed**: `groq` using LLaMA models.
  106. Whenever instantiating `ProcessorConfig`, be exact about paths—use absolute paths if the current working directory is dynamically changing.
README.md · README · 361 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="left">
  2. <img src="https://raw.githubusercontent.com/shoryasethia/markdrop/main/markdrop/src/markdrop-logo.png" alt="Markdrop Logo" width="200" height="200"/>
  3. <h1 style="display: inline; font-size: 2em; vertical-align: middle; padding-left: 10px; margin: 0;">Markdrop</h1>
  4. </p>
  5. [![Downloads](https://static.pepy.tech/badge/markdrop)](https://pepy.tech/projects/markdrop)
  6. [![PyPI Version](https://img.shields.io/pypi/v/markdrop)](https://pypi.org/project/markdrop/)
  7. [![License](https://img.shields.io/github/license/shoryasethia/markdrop)](https://github.com/shoryasethia/markdrop/blob/main/LICENSE)
  8. [![Stars](https://img.shields.io/github/stars/shoryasethia/markdrop?style=social)](https://github.com/shoryasethia/markdrop/stargazers)
  9. [![Issues](https://img.shields.io/github/issues/shoryasethia/markdrop)](https://github.com/shoryasethia/markdrop/issues)
  10. [![Forks](https://img.shields.io/github/forks/shoryasethia/markdrop?style=social)](https://github.com/shoryasethia/markdrop/network/members)
  11. A Python package for converting PDFs to structured Markdown and interactive HTML, with AI-powered image and table descriptions across **six major LLM providers**. Available on PyPI.
  12. ---
  13. ## Features
  14. - [x] PDF → Markdown conversion with formatting preservation (via Docling)
  15. - [x] Automatic image extraction using XRef IDs
  16. - [x] Table detection using Microsoft's Table Transformer
  17. - [x] PDF URL support
  18. - [x] AI-powered image and table descriptions — **6 providers**: Gemini, OpenAI, Anthropic Claude, Groq, OpenRouter, LiteLLM
  19. - [x] Interactive HTML output with downloadable Excel tables
  20. - [x] Customisable image resolution and UI elements
  21. - [x] Structured logging (never pollutes your app's root logger)
  22. ---
  23. ## Installation
  24. **Core install (PDF conversion + Gemini/OpenAI):**
  25. ```bash
  26. pip install markdrop
  27. ```
  28. **With Anthropic Claude:**
  29. ```bash
  30. pip install "markdrop[anthropic]"
  31. ```
  32. **With Groq:**
  33. ```bash
  34. pip install "markdrop[groq]"
  35. ```
  36. **With LiteLLM (routes to 100+ providers):**
  37. ```bash
  38. pip install "markdrop[litellm]"
  39. ```
  40. **Everything (including local HuggingFace models):**
  41. ```bash
  42. pip install "markdrop[all]"
  43. ```
  44. **Faster CPU / lightweight Markdown (`--fast` mode):**
  45. ```bash
  46. pip install "markdrop[lite]"
  47. markdrop convert report.pdf --output_dir out --fast
  48. ```
  49. See [docs/cpu-guide.md](docs/cpu-guide.md) for CPU-only and Colab guidance.
  50. > **OpenRouter** is accessed through the `openai` package (already included in core), so no extra install is needed.
  51. ---
  52. ## Supported AI Providers
  53. | Provider | `--ai_provider` | Default vision model | Default text model (tables) | Vision |
  54. |---|---|---|---|---|
  55. | Google Gemini | `gemini` | `gemini-3.1-flash-lite` | `gemini-3.1-flash-lite` | ✅ |
  56. | OpenAI | `openai` | `gpt-5.6-terra` | `gpt-5.6-luna` | ✅ |
  57. | Anthropic Claude | `anthropic` | `claude-opus-5` | `claude-sonnet-5` | ✅ |
  58. | Groq | `groq` | `meta-llama/llama-4-maverick-17b-128e-instruct` | `meta-llama/llama-4-scout-17b-16e-instruct` | ✅ |
  59. | OpenRouter | `openrouter` | `google/gemini-3.1-flash-lite` | `anthropic/claude-sonnet-5` | ✅ |
  60. | LiteLLM | `litellm` | `openai/gpt-5.6-terra` | `openai/gpt-5.6-luna` | ✅ |
  61. > All models are configurable — use `--model` to override for any provider, or set `model_name_override` in `ProcessorConfig`.
  62. ---
  63. ## Quick Start
  64. See [examples/quickstart.md](examples/quickstart.md) for copy-paste commands.
  65. [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1oApTrP_kjNn0s1tpE0SIWRyGzYfflQsi?usp=sharing)
  66. [![Watch the demo](https://img.shields.io/badge/YouTube-Demo-red?logo=youtube&logoColor=white)](https://youtu.be/2xg7W0-oiw0)
  67. ---
  68. ## CLI Usage
  69. Check the installed version:
  70. ```bash
  71. markdrop --version
  72. ```
  73. ### 1. Convert PDF → Markdown + HTML
  74. ```bash
  75. markdrop convert <input_path> --output_dir <dir> [--add_tables] [--fast]
  76. ```
  77. ```bash
  78. # Example
  79. markdrop convert report.pdf --output_dir out --add_tables
  80. # Outputs: out/report-markdroped.md and out/report-markdroped.html
  81. # Also works with URLs (SSRF-protected download):
  82. markdrop convert https://arxiv.org/pdf/1706.03762 --output_dir out
  83. ```
  84. ### 2. Generate AI Descriptions for Images & Tables
  85. ```bash
  86. markdrop describe <markdown_file> --ai_provider <provider> [--output_dir <dir>] [--remove_images] [--remove_tables]
  87. ```
  88. | Provider | `--ai_provider` |
  89. |---|---|
  90. | Google Gemini | `gemini` |
  91. | OpenAI | `openai` |
  92. | Anthropic Claude | `anthropic` |
  93. | Groq | `groq` |
  94. | OpenRouter | `openrouter` |
  95. | LiteLLM | `litellm` |
  96. ```bash
  97. # Gemini (default)
  98. markdrop describe doc.md --ai_provider gemini
  99. # Anthropic Claude
  100. markdrop describe doc.md --ai_provider anthropic --remove_images
  101. # Groq (fastest inference)
  102. markdrop describe doc.md --ai_provider groq
  103. # OpenRouter (any model)
  104. markdrop describe doc.md --ai_provider openrouter
  105. # LiteLLM (unified gateway)
  106. markdrop describe doc.md --ai_provider litellm
  107. ```
  108. ### 3. Set Up API Keys
  109. ```bash
  110. markdrop setup <provider>
  111. ```
  112. Keys are stored in your user config directory (via `platformdirs`, with a fallback to `~/.config/markdrop/`):
  113. - **Linux/macOS:** `~/.config/markdrop/.env` (or `$XDG_CONFIG_HOME/markdrop/.env`)
  114. - **Windows:** `%LOCALAPPDATA%\markdrop\.env`
  115. On POSIX systems, the `.env` file is written with `0o600` permissions.
  116. ```bash
  117. markdrop setup gemini # → GEMINI_API_KEY (GOOGLE_API_KEY also accepted)
  118. markdrop setup openai # → OPENAI_API_KEY
  119. markdrop setup anthropic # → ANTHROPIC_API_KEY
  120. markdrop setup groq # → GROQ_API_KEY
  121. markdrop setup openrouter # → OPENROUTER_API_KEY
  122. markdrop setup litellm # → LITELLM_API_KEY
  123. ```
  124. ### 4. Analyze Images in a PDF
  125. ```bash
  126. markdrop analyze report.pdf --output_dir pdf_analysis --save_images
  127. ```
  128. ### 5. Batch Image Description Generation
  129. ```bash
  130. markdrop generate images/ --output_dir descriptions/ --prompt "Describe in detail." \
  131. --llm_client gemini openai
  132. ```
  133. Available `--llm_client` values: `qwen`, `gemini`, `openai`, `llama-vision`, `molmo`, `pixtral`
  134. ---
  135. ## Python API
  136. ### PDF Conversion
  137. ```python
  138. from markdrop import markdrop, MarkDropConfig, add_downloadable_tables
  139. from pathlib import Path
  140. import logging
  141. config = MarkDropConfig(
  142. image_resolution_scale=2.0,
  143. download_button_color="#444444",
  144. log_level=logging.INFO,
  145. log_dir="logs",
  146. excel_dir="markdrop-excel-tables",
  147. )
  148. html_path = markdrop("path/to/input.pdf", "output", config)
  149. downloadable_html = add_downloadable_tables(html_path, config)
  150. ```
  151. ### AI Descriptions
  152. ```python
  153. import asyncio
  154. from markdrop import process_markdown, ProcessorConfig, AIProvider, setup_keys
  155. # One-time key setup (writes to user config ~/.config/markdrop/.env)
  156. setup_keys("anthropic")
  157. config = ProcessorConfig(
  158. input_path="out/report-markdroped.md",
  159. output_dir="output",
  160. ai_provider=AIProvider.ANTHROPIC, # GEMINI | OPENAI | ANTHROPIC | GROQ | OPENROUTER | LITELLM
  161. remove_images=False,
  162. remove_tables=False,
  163. table_descriptions=True,
  164. image_descriptions=True,
  165. max_retries=3,
  166. retry_delay=2,
  167. # Override default models (all providers have matching config fields):
  168. anthropic_model_name="claude-opus-5",
  169. anthropic_text_model_name="claude-sonnet-5",
  170. )
  171. output_path = asyncio.run(process_markdown(config))
  172. ```
  173. #### Using OpenRouter to access any model
  174. ```python
  175. config = ProcessorConfig(
  176. input_path="doc.md",
  177. output_dir="output",
  178. ai_provider=AIProvider.OPENROUTER,
  179. openrouter_model_name="meta-llama/llama-4-scout", # any model on openrouter.ai/models
  180. openrouter_text_model_name="anthropic/claude-sonnet-5",
  181. openrouter_site_url="https://yoursite.com",
  182. openrouter_site_name="My App",
  183. )
  184. ```
  185. #### Using LiteLLM for any 100+ provider
  186. ```python
  187. import os
  188. os.environ["ANTHROPIC_API_KEY"] = "..." # set any provider's key
  189. config = ProcessorConfig(
  190. input_path="doc.md",
  191. output_dir="output",
  192. ai_provider=AIProvider.LITELLM,
  193. litellm_model_name="anthropic/claude-opus-5",
  194. litellm_text_model_name="openai/gpt-5.6-luna",
  195. )
  196. ```
  197. ### Batch Image Description Generation
  198. ```python
  199. from markdrop import generate_descriptions
  200. generate_descriptions(
  201. input_path="images/",
  202. output_dir="output/",
  203. prompt="Give a highly detailed description of this image.",
  204. llm_client=["gemini", "llama-vision"],
  205. )
  206. ```
  207. ---
  208. ## API Reference
  209. ### `ProcessorConfig` – AI Provider Fields
  210. | Field | Default | Notes |
  211. |---|---|---|
  212. | `gemini_model_name` | `gemini-3.1-flash-lite` | Vision model |
  213. | `gemini_text_model_name` | `gemini-3.1-flash-lite` | Text model |
  214. | `openai_model_name` | `gpt-5.6-terra` | Vision |
  215. | `openai_text_model_name` | `gpt-5.6-luna` | Tables / text |
  216. | `anthropic_model_name` | `claude-opus-5` | Vision |
  217. | `anthropic_text_model_name` | `claude-sonnet-5` | Text (cheaper) |
  218. | `groq_model_name` | `meta-llama/llama-4-maverick-17b-128e-instruct` | Vision |
  219. | `groq_text_model_name` | `meta-llama/llama-4-scout-17b-16e-instruct` | Text |
  220. | `openrouter_model_name` | `google/gemini-3.1-flash-lite` | Any model string from openrouter.ai/models |
  221. | `openrouter_text_model_name` | `anthropic/claude-sonnet-5` | |
  222. | `litellm_model_name` | `openai/gpt-5.6-terra` | `provider/model` format |
  223. | `litellm_text_model_name` | `openai/gpt-5.6-luna` | |
  224. ### `MarkDropConfig`
  225. | Field | Default | Notes |
  226. |---|---|---|
  227. | `image_resolution_scale` | `2.0` | Scale factor for extracted images |
  228. | `download_button_color` | `'#444444'` | HTML button colour |
  229. | `log_level` | `logging.INFO` | |
  230. | `log_dir` | `'logs'` | |
  231. | `excel_dir` | `'markdrop_excel_tables'` | |
  232. ---
  233. ## Contributing
  234. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md). Please read our [Code of Conduct](CODE_OF_CONDUCT.md).
  235. ```bash
  236. git clone https://github.com/shoryasethia/markdrop.git
  237. cd markdrop
  238. python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate
  239. pip install -e .
  240. ```
  241. ---
  242. ## Project Structure
  243. ```
  244. markdrop/
  245. ├── setup.py
  246. ├── requirements.txt
  247. ├── README.md
  248. └── markdrop/
  249. ├── __init__.py
  250. ├── main.py ← CLI entry-point
  251. ├── process.py ← PDF conversion
  252. ├── parse.py ← AI description engine (all 6 providers)
  253. ├── helper.py ← PDF image analysis
  254. ├── utils.py ← PDF download helpers
  255. ├── setup_keys.py ← Interactive API key manager
  256. ├── ignore_warnings.py
  257. ├── src/
  258. │ └── markdrop-logo.png
  259. └── models/
  260. ├── img_descriptions.py
  261. ├── model_loader.py ← Local HF model loader
  262. ├── responder.py
  263. └── logger.py
  264. ```
  265. ---
  266. ## License
  267. GPL-3.0 — see [LICENSE](LICENSE).
  268. ## Changelog
  269. See [CHANGELOG.md](CHANGELOG.md).
  270. ## Support
  271. - [Open an issue](https://github.com/shoryasethia/markdrop/issues)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.