Agent-Skills.md

Agent Skills: PDF to Markdown

Convert a PDF book or document into clean, structured Markdown files split by chapter/section, with embedded images. Uses the Gemini Files API for high-quality conversion. Handles hyphenation repair, page-break paragraph joining, and blockquote formatting.

UncategorizedID: akaihola/skills-akaihola/pdf-to-markdown

Repository

akaihola/skills-akaihola
akaihola
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/akaihola/skills-akaihola/tree/HEAD/pdf-to-markdown

Skill Files

Browse the full folder contents for pdf-to-markdown.

Download Skill

Loading file tree…

pdf-to-markdown/SKILL.md

Skill Metadata

Name
pdf-to-markdown
Description
Convert a PDF book or document into clean, structured Markdown files split by chapter/section, with embedded images. Uses the Gemini Files API for high-quality conversion. Handles hyphenation repair, page-break paragraph joining, and blockquote formatting.

PDF to Markdown

Convert a structured PDF (book, report, manual) into clean Markdown files – one file per section – with images extracted and embedded.

Requirements

  • GEMINI_API_KEY environment variable set
  • uv available

Usage

Step 1: Create a config file

Create config.toml next to your PDF describing the sections and their page ranges:

pdf = "MyBook.pdf"
output_dir = "."
images_dir = "images"
model = "gemini-2.0-flash"          # optional, this is the default
rate_limit_sleep = 1.0              # seconds between API calls

[[sections]]
slug = "chapter-1"
start_page = 10
end_page = 53
heading = "# Chapter 1 – Introduction"
output = "chapters/01-introduction.md"

[[sections]]
slug = "chapter-2"
start_page = 54
end_page = 113
heading = "# Chapter 2 – Core Concepts"
output = "chapters/02-core-concepts.md"

[[sections]]
slug = "appendix-1"
start_page = 114
end_page = 121
heading = "# Appendix 1 – Self-Assessment"
output = "appendices/appendix-1.md"
# Optional: extra instructions appended to the prompt for this section
instructions = "Format all quiz questions as numbered lists."

Tips for setting page ranges:

  • Use a PDF viewer that shows physical page numbers (not printed numbers)
  • Sections that are too long (>~50 pages) may hit the model's output token limit – split them
  • Use gemini-2.0-flash (not flash-lite) for long sections

Step 2: Run the converter

GEMINI_API_KEY=your-key uv run ~/.claude/skills/pdf-to-markdown/scripts/convert.py config.toml

The script:

  1. Extracts all embedded images from the PDF with pymupdf
  2. Uploads the PDF once to the Gemini Files API
  3. Converts each section with a targeted prompt
  4. Fixes remaining hyphenation and page-break artifacts in post-processing
  5. Embeds image references at the correct locations
  6. Deletes the uploaded file from the API when done

Output structure

./
├── config.toml
├── images/
│   ├── image-01-page11.png
│   └── image-01-page22.png
└── chapters/
    ├── 01-introduction.md
    └── 02-core-concepts.md

Image paths in Markdown are relative from each output file to the images directory.

What Gemini handles well

  • Removing page numbers and headers/footers
  • Preserving heading hierarchy (##, ###)
  • Formatting block quotes (>)
  • Recognising section structure from visual layout

Known limitations

  • Footnote superscripts (¹ ²) and asterisk references (*) are reproduced as-is, not linked to their footnote text
  • Very long sections (>60 pages) may truncate – split them in config.toml
  • Image placement within a section is approximate (Gemini marks [IMAGE page N] which maps to extracted images by page number)