File Converter

Convert files between formats w/ single & batch support. All scripts use consistent CLI patterns.

When to Use

• Convert images between PNG, JPG, WEBP, BMP, TIFF, GIF, ICO, AVIF, HEIC/HEIF

• Resize/crop images w/ fit modes (contain, cover, fill, inside, outside)

• Convert markdown -> PDF or HTML w/ themes

• Convert HTML -> markdown (w/ tag stripping control)

• Transform CSV <-> JSON <-> YAML <-> TOML <-> XML

• SVG <-> raster conversion (PNG, JPG, WEBP, BMP, TIFF)

• Base64 encode/decode files (w/ data URI support, stdin)

• Fix text encoding issues (detect, convert w/ error handling strategies)

Quick Routing

Task Script Deps

Image convert/resize convert_image.py

Pillow, pillow-heif (opt)

Markdown -> HTML md_to_html.py

markdown, pygments

Markdown -> PDF md_to_pdf.py

markdown + weasyprint|pdfkit

HTML -> Markdown html_to_md.py

markdownify, bs4

CSV/JSON/YAML/TOML/XML csv_json_yaml.py

pyyaml, tomli-w, xmltodict, dicttoxml (per format)

SVG convert svg_convert.py

cairosvg, Pillow

Base64 encode/decode base64_codec.py

(none)

Text encoding text_encoding.py

chardet (opt)

Cross-platform utils platform_utils.py

(none) - shared by pdf/svg scripts

Install Deps

All deps (recommended)

pip install Pillow markdown pygments weasyprint markdownify beautifulsoup4 cairosvg pyyaml chardet tomli-w xmltodict dicttoxml

Optional

pip install pillow-heif # HEIC/HEIF support

Minimal (per task)

pip install Pillow # Images only pip install markdown pygments # MD -> HTML only pip install markdown weasyprint # MD -> PDF only (macOS: brew install pango) pip install markdownify beautifulsoup4 # HTML -> MD only pip install pyyaml # YAML support pip install tomli-w # TOML write (read: Python 3.11+ built-in) pip install xmltodict dicttoxml # XML support pip install cairosvg # SVG -> raster (macOS: brew install cairo) pip install chardet # Encoding detection

CLI Patterns

All scripts share consistent arg patterns:

Single file

python3 scripts/<script>.py input.ext output.ext

Batch (directory or glob)

python3 scripts/<script>.py *.ext --output-dir ./out python3 scripts/<script>.py ./dir/ --output-dir ./out --format ext

1. Image Convert & Resize

Format conversion

python3 scripts/convert_image.py photo.png photo.webp python3 scripts/convert_image.py photo.jpg photo.avif --quality 80

Resize

python3 scripts/convert_image.py photo.jpg thumb.jpg --width 300 python3 scripts/convert_image.py photo.png banner.png --width 1200 --height 400 --fit cover

Batch convert directory

python3 scripts/convert_image.py ./photos/ --output-dir ./webp --format webp --width 1200 --quality 85 python3 scripts/convert_image.py *.png --output-dir ./thumbs --format jpg --width 300 --height 300 --fit cover

Fit modes:

Mode Behavior

contain Fit inside bounds, preserve ratio (def)

cover Fill bounds, crop overflow

fill Stretch to exact dimensions

inside Like contain, but only shrink (never enlarge)

outside Like cover, but never crop

Supported: PNG, JPG, WEBP, BMP, TIFF, GIF, ICO, AVIF, HEIC/HEIF (w/ pillow-heif)

Auto-fixes EXIF orientation. Guards against decompression bombs (300M pixel limit).

2. Markdown -> HTML

Single file

python3 scripts/md_to_html.py README.md readme.html python3 scripts/md_to_html.py doc.md doc.html --theme dark

Batch

python3 scripts/md_to_html.py ./docs/ --output-dir ./site --theme github

Themes: github (def), dark, minimal, print

Features: fenced code blocks, syntax highlighting, tables, TOC w/ permalinks, responsive CSS.

3. Markdown -> PDF

Single file

python3 scripts/md_to_pdf.py report.md report.pdf python3 scripts/md_to_pdf.py spec.md spec.pdf --theme report

Batch

python3 scripts/md_to_pdf.py ./docs/ --output-dir ./pdfs --theme report

Themes: default, report (formal w/ serif), minimal

PDF engines: weasyprint (preferred, no external deps on macOS) or pdfkit (requires wkhtmltopdf). Script auto-detects available engine.

4. HTML -> Markdown

Single file

python3 scripts/html_to_md.py page.html page.md

Strip unwanted tags (default: script, style, noscript)

python3 scripts/html_to_md.py page.html page.md --strip script style nav footer

Keep all HTML tags (no stripping)

python3 scripts/html_to_md.py page.html page.md --keep-all

Batch

python3 scripts/html_to_md.py ./site/ --output-dir ./docs

5. Data Formats (CSV/JSON/YAML/TOML/XML)

Any direction

python3 scripts/csv_json_yaml.py data.csv data.json python3 scripts/csv_json_yaml.py data.json data.yaml python3 scripts/csv_json_yaml.py config.yaml config.json python3 scripts/csv_json_yaml.py config.toml config.json python3 scripts/csv_json_yaml.py data.json data.xml

Batch

python3 scripts/csv_json_yaml.py *.csv --output-dir ./json --format json

Supported: CSV, JSON, YAML (.yaml/.yml), TOML (.toml), XML (.xml). All directions supported where deps are installed.

6. SVG Conversion

SVG -> raster

python3 scripts/svg_convert.py icon.svg icon.png --width 512 python3 scripts/svg_convert.py logo.svg logo.jpg --width 1024 --quality 90

Raster -> SVG (embedded image wrapper)

python3 scripts/svg_convert.py photo.png photo.svg

Batch

python3 scripts/svg_convert.py *.svg --output-dir ./png --format png --width 256

7. Base64 Encode/Decode

Encode to stdout

python3 scripts/base64_codec.py encode image.png

Encode to data URI (for HTML/CSS embedding)

python3 scripts/base64_codec.py encode image.png --data-uri

Encode to file

python3 scripts/base64_codec.py encode image.png -o image.b64

Decode

python3 scripts/base64_codec.py decode image.b64 -o image.png

Batch

python3 scripts/base64_codec.py encode *.png --output-dir ./b64

8. Text Encoding

Detect encoding

python3 scripts/text_encoding.py detect file.txt python3 scripts/text_encoding.py detect *.txt

Convert encoding (single mode requires -o to prevent accidental overwrite)

python3 scripts/text_encoding.py convert file.txt --to utf-8 -o output.txt python3 scripts/text_encoding.py convert file.txt --from latin-1 --to utf-8 -o output.txt

Handle unmappable characters

python3 scripts/text_encoding.py convert file.txt --to ascii --errors replace -o clean.txt python3 scripts/text_encoding.py convert file.txt --to ascii --errors ignore -o clean.txt

Batch convert to UTF-8

python3 scripts/text_encoding.py convert *.txt --to utf-8 --output-dir ./utf8

Error modes: strict (default, fail on unmappable), replace (use ? placeholder), ignore (skip unmappable chars).

Common Workflows

Web optimization pipeline

Convert photos to WEBP, resize for web, generate thumbnails

python3 scripts/convert_image.py ./photos/ --output-dir ./web --format webp --width 1200 --quality 80 python3 scripts/convert_image.py ./photos/ --output-dir ./thumbs --format webp --width 300 --height 300 --fit cover --quality 75

Documentation pipeline

Generate HTML site from markdown docs

python3 scripts/md_to_html.py ./docs/ --output-dir ./site --theme github

Generate PDF reports

python3 scripts/md_to_pdf.py ./docs/ --output-dir ./pdfs --theme report

Data migration pipeline

CSV -> JSON for API import

python3 scripts/csv_json_yaml.py ./exports/ --output-dir ./json --format json

JSON config -> YAML

python3 scripts/csv_json_yaml.py config.json config.yaml

Icon generation pipeline

SVG -> multiple PNG sizes for app icons

for size in 16 32 64 128 256 512; do python3 scripts/svg_convert.py icon.svg "icon-${size}.png" --width $size done

Error Handling

All scripts:

• Print errors per-file in batch mode, continue w/ remaining files

• Exit 1 on fatal errors (missing deps, no input)

• Print size before/after for each conversion

• Create output directories automatically

• Handle KeyboardInterrupt gracefully (exit 130)

Cross-Platform Support

Scripts work on macOS, Linux, and Windows. Native library paths (cairo, pango, gobject) are auto-configured via platform_utils.py :

• macOS: /opt/homebrew/lib , /usr/local/lib

• Linux: /usr/local/lib , /usr/lib/x86_64-linux-gnu

• Windows: GTK runtime, MSYS2, Conda paths + os.add_dll_directory()

Stdin Support

md_to_html.py and base64_codec.py accept - for stdin input:

cat README.md | python3 scripts/md_to_html.py - output.html cat file.bin | python3 scripts/base64_codec.py encode - -o file.b64

Integration

Pairs with: token-optimizer (compress markdown before PDF), code-quality (validate scripts)