pdf-to-markdown

Converts court process PDFs into structured Markdown files organized by document type.

1|Updated May 8, 2026
One-click install
npx skills add https://github.com/franklinbaldo/skills --skill pdf-to-markdown-franklinbaldo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pdf-to-markdown
Source: https://github.com/franklinbaldo/skills/tree/main/pdf-to-markdown
Command: npx skills add https://github.com/franklinbaldo/skills --skill pdf-to-markdown-franklinbaldo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires cyclopts, markitdown, pymupdf, and includes scripts (resource) components.

What problem does it solve? Judicial processes downloaded from systems like PJe, SEI, or Kanoê arrive as large merged PDFs that are hard to read, search, or feed into analysis workflows. This Skill converts them into clean, structured Markdown, splitting each document (sentença, despacho, petição, etc.) into its own file inside a case-numbered directory. ## Core Features & Use Cases - Automatic document splitting: Detects document boundaries inside merged court PDFs using title markers (SENTENÇA, DECISÃO, DESPACHO, PETIÇÃO INICIAL) and saves each as a separate .md file. - Dual extraction engines: Prefers markitdown for high-fidelity conversion, with a PyMuPDF fallback for offline or credential-free environments; optional Azure Document Intelligence OCR for scanned PDFs. - Case index generation: Produces an INDEX.md with the case number (CNJ/NUP) and a linked table of all extracted documents. - Use Case: You download a 500-page process from PJe and need each peça processual as a separate searchable Markdown file for legal analysis or LLM ingestion. ## Quick Start Ask the agent to convert the attached court process PDF into a folder of Markdown files organized by document type, using the case number as the directory name.

Frequently Asked Questions about pdf-to-markdown

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert a court process PDF to Markdown?▼

Run the convert_pdf.py script with uv, passing --input for the PDF path and --outdir for the output directory. It uses markitdown by default and falls back to PyMuPDF, saving each detected document as a separate .md file plus an INDEX.md.

How to split a merged PJe PDF into separate documents?▼

The script detects document boundaries using title markers like SENTENÇA, DESPACHO, DECISÃO, and PETIÇÃO found at page starts. Each detected section is saved as a numbered Markdown file named after the document type.

markitdown vs PyMuPDF for PDF text extraction?▼

markitdown produces higher-fidelity Markdown but returns a single stream without page boundaries. PyMuPDF extracts one chunk per real page, enabling Page N comments in the output, and works fully offline as the fallback extractor.

Can I convert scanned PDFs without selectable text?▼

Yes, by passing --docintel-endpoint with an Azure Document Intelligence URL and credentials in the environment. This routes conversion through cloud OCR and layout analysis instead of local text extraction.

Why are there no page number comments in my Markdown output?▼

Missing page comments mean the markitdown path ran, which returns a single Markdown stream without page boundaries. Page comments only appear when the PyMuPDF fallback extracts real per-page chunks.