External images in Markdown are a risk. I built a tool to solve this, focusing on simple architecture and testability.
Have you ever opened an old GitHub repository or a blog post only to find "broken image" icons everywhere?
It happens because we rely on external hosts. If the host goes down, your documentation dies.
In my last articles, I talked about Senior Mindset and Simple Architecture. Today, I’m putting those words into practice. I built MIL (Markdown Image Localizer): a CLI tool that finds remote images in your files, downloads them locally, and updates your links automatically.
Here is how I built it and why the "how" matters more than the code itself.
The Problem: The Fragility of the Web
We often use direct links for images in Markdown.
- Dependency: If the source site changes, your image breaks.
- Offline Access: You can't read your docs properly without internet.
- Manual Labor: Downloading 20 images and updating 20 links manually is a waste of an engineer's time.
The Solution: MIL (Markdown Image Localizer)
I designed this tool following three core principles: Simplicity, Separation of Concerns, and Testability.
1. Simple Architecture
Instead of one giant file, I split the logic:
-
Parser: Pure logic to find URLs using Regex. -
Downloader: Handles the I/O and HTTP requests. -
Processor: Orchestrates the flow. -
CLI: The entry point that talks to the user.
Why? Because if I want to turn this into a VS Code extension or a Web API tomorrow, the "Core" logic is already isolated.
2. Reliability through Testing
I didn't just "hope" the Regex worked. I implemented unit tests using Jest.
Before the first commit, I ensured that:
- It ignores local images.
- It handles duplicate URLs (no redundant downloads).
- It returns empty results when no images exist.
"Code without tests is just a rumor."
See the Code
You can check the full source code, the folder structure, and the tests here:
👉 GitHub: markdown-image-localizer
How to run it:
bash
git clone [https://github.com/rj-dev/markdown-image-localizer](https://github.com/rj-dev/markdown-image-localizer)
npm install
node index.js your-file.md
Top comments (0)