Markdown Image Embedder

embed_images.py converts local image references in a Markdown document into inline data: URIs so the file becomes completely self-contained. It understands standard Markdown image syntax, creates a backup of the original file, and offers optional controls for downsampling or constraining the size of the embedded payloads.

Features

• Replaces local image paths with Base64-encoded data: URIs and creates a .bak backup.
• Expands ~ in relative paths and resolves files relative to the Markdown document.
• Skips remote URLs automatically and preserves titles/alt text.
• Optional --max-width / --max-height flags resize images before embedding.
• Optional --max-bytes flag enforces a best-effort maximum size (in bytes) for every embedded image, including any images that were already embedded as data: URIs.
• Emits warnings for missing or unreadable assets without aborting the entire run.

Installation

1. Ensure you have Python 3.8 or newer installed.
2. Install the tool (and optional dependencies) into your environment:

   pip install .[resize]

   This installs the package along with Pillow so the resizing and max-bytes features work. If you only need basic embedding, pip install . is enough.

Usage

markdown-image-embedder [-h] [--max-width MAX_WIDTH] [--max-height MAX_HEIGHT]
                        [--max-bytes MAX_BYTES] path/to/file.md

Positional Arguments

• path/to/file.md – Markdown file to process. A backup copy will be written as file.md.bak.

Optional Arguments

• --max-width MAX_WIDTH – Downsample images wider than this pixel width.
• --max-height MAX_HEIGHT – Downsample images taller than this pixel height.
• --max-bytes MAX_BYTES – Best-effort upper bound (in bytes) for each embedded Base64 payload. Applies to local files and existing data: URIs.
• -h, --help – Show help text and exit.

Examples

Embed all local images without resizing:

markdown-image-embedder docs/report.md

Embed images, constraining them to 1200px wide and 300kB of Base64 data:

markdown-image-embedder --max-width 1200 --max-bytes 300000 docs/report.md

Notes

• The script only processes inline image syntax (![alt](path "title")). Reference-style links are left untouched.
• If an image cannot be found or read, the script logs a warning and leaves the original Markdown unchanged for that image.
• When resizing is requested but Pillow is not installed, the script exits with an informative message.

License

MIT License

Development

• Run the smoke tests before pushing changes:

  python3 -m unittest discover -s tests