file-converter

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)