pdf-convert
/pdf-convert
[Document Processing] Use when converting between PDF and Markdown: text PDFs to Markdown (scanned PDFs are reported, not OCR''d), Markdown to styled PDF. --to={markdown|pdf}.
- Author
- duc01226 ↗
- Repository
- EasyPlatform ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 23
- Scripts
- 18
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 18 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/convert.cjs, tests/dispatcher.test.cjs, to-markdown/scripts/convert.cjs, to-markdown/scripts/lib/converter.cjs, to-markdown/scripts/lib/output-handler.cjs, to-markdown/scripts/lib/pdf-detector.cjs, to-markdown/tests/converter.test.cjs, to-markdown/tests/run-tests.cjs
What it does and when to use it
[Document Processing] Use when converting between PDF and Markdown: text PDFs to Markdown (scanned PDFs are reported, not OCR''d), Markdown to styled PDF. --to={markdown|pdf}.
Original author description
[Document Processing] Use when converting between PDF and Markdown: text PDFs to Markdown (scanned PDFs are reported, not OCR''d), Markdown to styled PDF. --to={markdown|pdf}.
How it works
- Quick Summary
- Contents
- Directions
- Installation Required
- Quick Start
- CLI Options
- Features
- Conversion Modes (--to markdown)
- Default Styling (--to pdf)
- Output
SKILL.md preview
---
name: pdf-convert
version: 2.0.1
description: '[Document Processing] Use when converting between PDF and Markdown: text PDFs to Markdown (scanned PDFs are reported, not OCR''d), Markdown to styled PDF. --to={markdown|pdf}.'
disable-model-invocation: true
---
## Quick Summary
**Goal:** Convert PDF to Markdown, or Markdown to PDF, through one entry point.
**Summary:** Select the required direction → probe its dependencies → install only if missing → convert → check JSON status and the output file. Native text extraction and PDF rendering are supported; scanned-PDF OCR is unavailable.
**Workflow:**
1. **Pick a direction** — `--to markdown` (PDF in, Markdown out) or `--to pdf` (Markdown in, PDF out)
2. **Check that direction** — probe its dependencies; each has its own `package.json`, so install only missing dependencies for the selected direction
3. **Convert** — run `scripts/convert.cjs --to <direction>` with the direction's own options
4. **Output** — the converter returns JSON with the success status and output path
**Key Rules:**
- `--to` is required. There is no default direction — converting the wrong way silently is worse than an error.
- Every other argument is passed straight to the chosen converter, so each direction keeps its own CLI.
- Dependencies are per direction: `--to markdown` never pulls in the PDF renderer, and vice versa.
**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**
## Contents
- [Quick Summary](#quick-summary)
- [pdf-convert](#pdf-convert)
- [Directions](#directions)
- [Installation Required](#installation-required)
- [Quick Start](#quick-start)
- [CLI Options](#cli-options)
- [Features](#features)
- [Conversion Modes (`--to markdown`)](#conversion-modes---to-markdown)
- [Default Styling (`--to pdf`)](#default-styling---to-pdf)
- [Output](#output)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting)
- [Tests](#tests)
- [Closing Reminders](#closing-reminders)
# pdf-convert
Convert PDF files to Markdown (with automatic detection of native text vs scanned documents) and
Markdown files to high-quality PDF (with code syntax highlighting and custom CSS).
## Directions
| Flag | Converts | Lives in | Dependencies |
| ----------------- | --------------- | ------------ | ---------------------------------------- |
| `--to markdown` | PDF → Markdown | `to-markdown/` | `@opendocsg/pdf2md`, `pdfjs-dist` |
| `--to pdf` | Markdown → PDF | `to-pdf/` | `md-to-pdf`, `gray-matter` |
## Installation Required
Use Node.js >=18 for PDF → Markdown; for Markdown → PDF, use the runtime range in `to-pdf/package.json`. From the project root, probe the selected consumer's dependencies with `createRequire` before installing:
```bash
node -e "const p=require('node:path'); const r=require('node:module').createRequire(p.resolve('.claude/skills/pdf-convert/to-markdown/package.json')); r.resolve('@opendocsg/pdf2md');"
node -e "const p=require('node:path'); const r=require('node:module').createRequire(p.resolve('.claude/skills/pdf-convert/to-pdf/package.json')); r.resolve('md-to-pdf'); r.resolve('gray-matter');"
```
**Each direction installs separately.** Run only the probe and setup for the direction you need; its manifest owns package versions. Install missing dependencies with:
```bash
# PDF -> Markdown
cd .claude/skills/pdf-convert/to-markdown
npm install
# Markdown -> PDF
cd .claude/skills/pdf-convert/to-pdf
npm install
```
`ck init` (which runs `install.sh`) handles every skill at once.
**Note:** `--to pdf` may download Chromium (~150MB) on first run unless system Chrome is detected.
Scanned-PDF OCR is unimplemented. Installing optional OCR packages does not enable it.
## Quick Start
```bash
# PDF -> Markdown (auto-detects native text vs scanned)
node .claude/skills/pdf-convert/scripts/convert.cjs --to markdown --input ./document.pdf
# PDF -> Markdown with an explicit output path and forced native mode
node .claude/skills/pdf-convert/scripts/convert.cjs --to markdown -i ./doc.pdf -o ./out.md --mode native
# Markdown -> PDF
node .claude/skills/pdf-convert/scripts/convert.cjs --to pdf --input ./README.md
# Markdown -> PDF with custom CSS
node .claude/skills/pdf-convert/scripts/convert.cjs --to pdf -i ./doc.md --css ./my-style.css
```
`--to=markdown` and `--to markdown` are equivalent. A missing or unknown `--to` prints the valid
directions and exits 1.
## CLI Options
### Dispatcher
| Option | Description | Default |
| -------- | ---------------------------------------------- | ---------- |
| `--to` | Conversion direction: `markdown` or `pdf` | (required) |
### `--to markdown` (PDF → Markdown)
| Option | Short | Description | Default |
| ---------- | ----- | ---------------------------------------- | ------------ |
| `--input` | `-i` | Input PDF file path | (required) |
| `--output` | `-o` | Output markdown file path | `{input}.md` |
| `--mode` | `-m` | Conversion mode: `auto`, `native`, `ocr` | `auto` |
| `--help` | `-h` | Show help message | |
### `--to pdf` (Markdown → PDF)
| Option | Short | Description | Default |
| ---------------- | ----- | --------------------------- | ------------- |
| `--input` | `-i` | Input markdown file path | (required) |
| `--output` | `-o` | Output PDF file path | `{input}.pdf` |
| `--css` | `-c` | Custom CSS file path | built-in |
| `--no-highlight` | | Disable syntax highlighting | false |
| `--help` | `-h` | Show help message | |
Run `scripts/convert.cjs --to <direction> --help` to see a direction's full help.
## Features
**PDF → Markdown**
- **Auto-Detection:** determines whether the PDF has native text or needs OCR
- **Native PDFs:** fast extraction via `@opendocsg/pdf2md`
- **Tables:** basic table structure preservation
- **No System Dependencies:** pure JavaScript
**Markdown → PDF**
- **Syntax Highlighting:** code blocks rendered with highlight.js
- **Custom CSS:** override the default stylesheet with your own
- **System Chrome:** uses installed Chrome/Chromium when available
- **Frontmatter Support:** YAML frontmatter supplies the title and metadata
Both directions work on Windows, macOS and Linux.
## Conversion Modes (`--to markdown`)
### Auto (default)
Checks whether the first page has extractable text. Uses native extraction if it does, otherwise
reports that the document appears to be scanned.
### Native
Fast direct text extraction. Best for PDFs with selectable text.
### OCR (scanned PDFs) — unsupported
The converter returns a failure for OCR mode. Report the limitation for scanned documents; native mode is suitable only when the PDF contains selectable text.
## Default Styling (`--to pdf`)
- Serif body font (Georgia), monospace code font (Consolas/Monaco)
- 2cm page margins
- Code block background highlighting
- Table borders with alternating row colors
Override any of it with `--css`.
## Output
Both directions return JSON on success:
```json
{
"success": true,
"input": "/path/to/input.pdf",
"output": "/path/to/output.md",
"stats": {
"pages": 5,
"mode": "native"
}
}
```
`--to pdf` returns `pages` instead of `stats`. On failure both return
`{ "success": false, "error": "..." }` and exit 1.
## Limitations
- Complex multi-column layouts may not preserve structure
- Scanned PDFs cannot be transcribed by this converter
- Mathematical formulas may not convert perfectly
- Large documents converted to PDF may need more memory — consider splitting the input
## Troubleshooting
**Chrome not found (`--to pdf`):** the converter downloads Chromium automatically. Set
`PUPPETEER_SKIP_DOWNLOAD=1` to prevent that.
**Missing dependencies:** the error output carries a `hint` with the exact `cd … && npm install`
command for the direction you invoked.
**Font issues:** embed fonts via CSS `@font-face` with base64-encoded fonts for consistent rendering.
## Tests
```bash
cd .claude/skills/pdf-convert && node tests/dispatcher.test.cjs # routing and --to validation
cd .claude/skills/pdf-convert/to-markdown && node tests/run-tests.cjs
cd .claude/skills/pdf-convert/to-pdf && node tests/run-tests.cjs
```
---
> **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting. This prevents context loss from long files. Keep task depth proportional to the work.
## Closing Reminders
**IMPORTANT MUST ATTENTION Goal:** Convert PDF to Markdown, or Markdown to PDF, through one entry point — `scripts/convert.cjs --to {markdown|pdf}`.
**MUST ATTENTION Route:** select direction → probe dependencies → install only if missing → convert → verify JSON status and the output file. Report unsupported OCR; optional package installation cannot enable it.
**IMPORTANT MUST ATTENTION** `--to` is required — never guess the direction for the user
**IMPORTANT MUST ATTENTION** each direction installs its own dependencies; the error `hint` names the exact directory
**IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting
**IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code
**IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act)
**IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality
**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.
Files in this package (23)
- SKILL.md 10 KB
- scripts/convert.cjs 3 KB
- tests/dispatcher.test.cjs 4 KB
- to-markdown/package.json 1 KB
- to-markdown/scripts/convert.cjs 5 KB
- to-markdown/scripts/lib/converter.cjs 4 KB
- to-markdown/scripts/lib/output-handler.cjs 1 KB
- to-markdown/scripts/lib/pdf-detector.cjs 2 KB
- to-markdown/tests/converter.test.cjs 4 KB
- to-markdown/tests/run-tests.cjs 1 KB
- to-markdown/tests/test-framework.cjs 3 KB
- to-pdf/package.json 1 KB
- to-pdf/assets/default-style.css 2 KB
- to-pdf/scripts/convert.cjs 5 KB
- to-pdf/scripts/lib/chrome-finder.cjs 3 KB
- to-pdf/scripts/lib/config-loader.cjs 3 KB
- to-pdf/scripts/lib/converter.cjs 4 KB
- to-pdf/scripts/lib/output-handler.cjs 3 KB
- to-pdf/tests/chrome-finder.test.cjs 2 KB
- to-pdf/tests/converter.test.cjs 5 KB
- to-pdf/tests/run-tests.cjs 1 KB
- to-pdf/tests/test-framework.cjs 4 KB
- to-pdf/tests/fixtures/sample.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · duc01226/EasyPlatform | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
Database snapshot: 13.11.2026 · package version d328f72da493 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 2 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100document-processing
This skill should be used when the user says \"process documents\", \"extract text from PDF\", \"OCR this document\", \"convert PDF to markdown\", \"extract emails from documents\", \"parse document\", \"document conversion\", \"batch OCR\", \"extract structured data from PDF\",… - 100create-pdf
Convert markdown files into a styled PDF. Use when creating a PDF from existing markdown files, combining markdown into a report, or converting .md to .pdf. - 100roascan
Ultra-fast local C++17 & ONNX multi-page OCR and document restoration tool (RoaScan). Use whenever you need to read scanned PDFs, multi-page TIFFs, or document images, convert scanned documents into structured Markdown (.md) with tables (|---|---|), or generate restored,… - 100convert-pdf
Convert PDF to clean markdown. Auto-detects backend: pdftotext (fast, text-heavy) or docling (complex tables, multi-column, OCR). Use when converting PDFs to markdown for analysis or summarization. Triggers: "convert pdf", "pdf to markdown", "pdf file", "pdf to text", ".pdf". - 100mistral-pdf-to-markdown
Convert PDFs to Markdown with Mistral OCR and extracted images. Use for scanned PDFs or complex layouts where structured text or images matter. - 100pdf-to-md
Convert PDF documents to Markdown using a local docling + RapidOCR setup. Use this whenever the user wants to turn a PDF into Markdown or plain text — extract text/tables/headings from a PDF, get a PDF's content as .md, prep a PDF for an LLM or RAG pipeline, OCR a scanned PDF to…