document-converter

Purpose

Convert documents between formats and perform PDF operations using local, free, offline tools. No API key, no cost, no internet required. Supports Office formats, PDF manipulation, image-to-PDF, and OCR using LibreOffice, ghostscript, pdftk, tesseract, and imagemagick.

When to Use

• Converting Office documents (DOCX, PPTX, XLSX, ODP, ODT) to PDF or HTML
• Converting PDF pages to images (PNG, JPG, TIFF) or images to PDF
• PDF operations: merge multiple PDFs, split by page range, rotate pages, encrypt or decrypt
• OCR: extract searchable text from scanned PDFs or image files
• Any document format conversion that does not involve video or audio

Do NOT use for:

• Video or audio format conversion (use a dedicated media skill)
• Converting code between programming languages
• Simple markdown → HTML (use pandoc directly)
• Structured text extraction from PDFs (use docling-converter instead)

Step 0: Discovery — Detect Available Tools

Before any conversion, detect which tools are installed and identify the operating system:

# Detect OS
uname -s   # Darwin = macOS, Linux = Linux; on Windows use 'ver' or check $OS

# Check each tool
libreoffice --version 2>/dev/null || echo "NOT FOUND"
gs --version 2>/dev/null || echo "NOT FOUND"
pdftk --version 2>/dev/null || echo "NOT FOUND"
tesseract --version 2>/dev/null || echo "NOT FOUND"
convert -version 2>/dev/null || echo "NOT FOUND"   # ImageMagick

If a required tool is missing, show the install command for the user's OS before proceeding:

Tool	macOS	Linux (apt)	Windows
LibreOffice	brew install --cask libreoffice	sudo apt install libreoffice	winget install TheDocumentFoundation.LibreOffice
Ghostscript	brew install ghostscript	sudo apt install ghostscript	winget install ArtifexSoftware.GhostScript
pdftk	brew install pdftk-java	sudo apt install pdftk	winget install PDFTechnologies.PDFtk
Tesseract	brew install tesseract	sudo apt install tesseract-ocr	winget install UB-Mannheim.TesseractOCR
ImageMagick	brew install imagemagick	sudo apt install imagemagick	winget install ImageMagick.ImageMagick

If the user is on Windows and Microsoft Office is installed, note that LibreOffice and Office produce equivalent results for DOCX/PPTX/XLSX; Office via COM automation is an advanced alternative.

Workflow

Office Documents → PDF (most common)

Use LibreOffice headless mode. Works for DOCX, PPTX, XLSX, ODP, ODT, and any format LibreOffice opens.

# Convert single file to PDF in the same directory
libreoffice --headless --convert-to pdf "/path/to/file.pptx" --outdir "/path/to/output/"

# Convert to HTML
libreoffice --headless --convert-to html "/path/to/file.docx" --outdir "/path/to/output/"

# Batch: convert all PPTX in a directory
libreoffice --headless --convert-to pdf /path/to/folder/*.pptx --outdir /path/to/output/

Notes:

• Output file is placed in --outdir with the same base name and new extension
• For batch, run one libreoffice process — do NOT spawn multiple instances in parallel (LibreOffice uses a single user profile lock)
• If LibreOffice is open as a GUI app, close it first or use --norestore flag

PDF → Images / Images → PDF

Use ImageMagick for image-PDF interchange:

# PDF pages → PNG (one file per page)
convert -density 150 "/path/to/doc.pdf" "/path/to/output/page_%03d.png"

# PDF pages → JPG with quality control
convert -density 150 "/path/to/doc.pdf" -quality 85 "/path/to/output/page_%03d.jpg"

# Single image → PDF
convert "/path/to/image.png" "/path/to/output/document.pdf"

# Multiple images → single PDF
convert img1.png img2.jpg img3.tiff "/path/to/output/combined.pdf"

Note: On some systems ImageMagick's PDF support requires ghostscript. If conversion fails with a policy error, check /etc/ImageMagick-*/policy.xml and ensure PDF is not restricted.

PDF Operations — Merge, Split, Rotate

Prefer pdftk when available (simpler syntax). Fall back to ghostscript if pdftk is not installed.

Merge PDFs:

# pdftk (preferred)
pdftk file1.pdf file2.pdf file3.pdf cat output merged.pdf

# ghostscript (fallback)
gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -sOutputFile=merged.pdf file1.pdf file2.pdf file3.pdf

Split PDF by page range:

# pdftk — extract pages 1-3 and 5
pdftk input.pdf cat 1-3 5 output extracted.pdf

# ghostscript — extract pages 2 to 5
gs -dBATCH -dNOPAUSE -q -sDEVICE=pdfwrite -dFirstPage=2 -dLastPage=5 -sOutputFile=extracted.pdf input.pdf

Rotate pages:

# pdftk — rotate all pages 90° clockwise
pdftk input.pdf rotate 1-endeast output rotated.pdf

# pdftk — rotate specific page (page 3) 180°
pdftk input.pdf rotate 3south output rotated.pdf

Encrypt PDF (add password):

pdftk input.pdf output secured.pdf user_pw "userpass" owner_pw "ownerpass"

Decrypt PDF (remove password):

pdftk secured.pdf input_pw "password" output decrypted.pdf

OCR — Extract Text from Scanned Documents

Use Tesseract. Input must be an image (PNG, JPG, TIFF) or a PDF that ImageMagick can rasterize first.

# OCR a single image → searchable text file
tesseract "/path/to/scan.png" "/path/to/output/result"
# Output: result.txt

# OCR with language specification (Portuguese example)
tesseract "/path/to/scan.png" output -l por

# OCR → searchable PDF (requires tesseract with pdf support)
tesseract "/path/to/scan.png" output -l eng pdf
# Output: output.pdf

# OCR a scanned PDF: rasterize first, then OCR
convert -density 300 "scan.pdf" "scan_page_%03d.tiff"
tesseract "scan_page_000.tiff" output -l eng pdf

For multi-page scanned PDFs:

# Rasterize all pages
convert -density 300 "scan.pdf" "page_%03d.tiff"

# OCR each page and merge results
for f in page_*.tiff; do
  tesseract "$f" "${f%.tiff}" -l eng pdf
done
pdftk page_*.pdf cat output final_ocr.pdf

Tool Routing Decision Table

Task	Primary tool	Fallback
Office → PDF	LibreOffice	None (LibreOffice is the standard)
Office → HTML	LibreOffice	None
PDF → images	ImageMagick	ghostscript (gs -sDEVICE=png16m)
Images → PDF	ImageMagick	ghostscript
Merge PDFs	pdftk	ghostscript
Split PDF	pdftk	ghostscript
Rotate PDF	pdftk	ghostscript
Encrypt PDF	pdftk	None
Decrypt PDF	pdftk	None
OCR	tesseract	None

Comparison: When to Use document-converter vs Alternatives

Tool	Best for
document-converter	Office → PDF, PDF operations (merge/split/rotate/encrypt), OCR, image ↔ PDF
docling-converter	PDF/Office → structured Markdown or JSON; layout-aware content extraction
pandoc	Markdown ↔ HTML ↔ LaTeX ↔ DOCX; lightweight lightweight text format conversions
pptx-translator	Translating PowerPoint files between languages

Critical Rules

• NEVER start a batch LibreOffice conversion with multiple parallel processes — LibreOffice uses a single user-profile lock and parallel instances will crash
• ALWAYS run Step 0 Discovery to confirm the required tool is installed before invoking it
• ALWAYS suggest the correct install command for the user's OS when a tool is missing
• NEVER use cloudconvert, external APIs, or paid services — this skill is fully offline
• ALWAYS prefer pdftk over ghostscript for PDF operations when both are available (simpler, safer syntax)
• ALWAYS specify output directory explicitly to avoid writing files to unexpected locations

Example Usage

Convert PPTX to PDF:

libreoffice --headless --convert-to pdf presentation.pptx --outdir ./output/

Merge 3 PDFs:

pdftk report.pdf appendix.pdf cover.pdf cat output final.pdf

OCR a scanned image (Portuguese):

tesseract scan.png resultado -l por

PDF pages to PNG images:

convert -density 150 document.pdf page_%03d.png

Encrypt a PDF:

pdftk sensitive.pdf output protected.pdf user_pw "secret123"