md-localize-images

md-localize-images scans Markdown files, downloads remote image references, stores them locally, and rewrites the image links.

The tool is intended for Obsidian vaults, but it also works with ordinary Markdown files. The default rewritten link style is Obsidian embed syntax:

![[attachments/image.png]]

Install for development

python -m pip install -e ".[dev]"

Usage

Process one file:

md-localize-images --file path/to/note.md

Process a vault recursively:

md-localize-images --vault path/to/vault --recursive

Choose where downloaded images are stored:

md-localize-images --file note.md --images-dir attachments/imported-images

Use relative Markdown links instead of Obsidian links:

md-localize-images --file note.md --link-style relative

Run without writing files:

md-localize-images --vault . --recursive --dry-run

Create Markdown backups before modification:

md-localize-images --vault . --recursive --backup

Process raw HTML image tags as well as Markdown images:

md-localize-images --vault . --recursive --include-html-img

Exit Codes

• 0: success
• 1: one or more downloads failed, but processing completed
• 2: invalid command-line arguments
• 3: filesystem or path configuration error

Notes

• WebP images are saved as PNG files.
• Links inside fenced code blocks, indented code blocks, inline code spans, and HTML comments are not modified.
• Existing image files are not overwritten; a deterministic hash is added to avoid collisions.
• Repeated identical URLs are downloaded once per invocation.
• Phase one does not include a persistent cache.