How to repair broken markdown image paths
- Step 1List what's broken — Run the document through the link validator to get a report of references that don't resolve, so you know the exact wrong fragment.
- Step 2Load it into the rewriter — Paste the Markdown or upload the
.md/.mdx/.markdown/.txtfile here. - Step 3Enter the wrong fragment — Type the broken path piece into Find, e.g.
old-assets/or../img/. - Step 4Enter the correct fragment — Type the corrected path into Replace, e.g.
assets/or/static/img/. Leave Find empty instead to prepend a corrected base. - Step 5Regex for variable breakages — If the broken part differs per path, tick Treat Find as regex and capture the stable part with
$1. - Step 6Run, re-validate, save — Click Run Image Paths, re-run the validator on the output to confirm nothing is still broken, then download.
Common breakages and the fix
Map the symptom to the right Find/Replace/regex settings.
| Symptom | Find | Replace | Regex |
|---|---|---|---|
| Asset folder renamed | old-assets/ | assets/ | off |
| Stale parent traversal | ../ | (empty or correct base) | off |
| Whole doc lost its base | empty | /static/img/ | off |
| Wrong segment, varies per file | ^.*/(images/.+)$ | /$1 | on |
What the matcher catches
Only these forms are eligible for repair; everything else is passed through unchanged.
| Reference form | Repairable? | Note |
|---|---|---|
 | Yes | Standard inline image |
 | Yes | Title kept intact |
[id]: path | Yes | Reference definitions (image or link) |
 | No | Un-encoded space breaks the match — encode as %20 |
 | No | Angle-bracket form not recognised |
 | No | Absolute URL — skipped even if the host 404s |
Plan limits (markdown family)
Size and character ceilings per tier.
| Plan | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10 |
| Pro-media | 50 MB | 20,000,000 | 50 |
| Developer | 500 MB | unlimited | unlimited |
Cookbook
Recovery recipes for the usual ways image paths break. Validate first, fix here, re-validate.
Renamed asset folder
The folder was renamed from old-assets to assets; a literal swap fixes every reference.
Find: old-assets/ Replace: assets/ Regex: off Before:  After: 
Strip a stale parent traversal
Copied content carried a wrong ../ prefix; remove it and the path resolves from the doc's folder.
Find: ../ Replace: (empty) Regex: off Before:  After: 
Restore a lost base path
All images lost their /static/img/ base after a CMS move; prepend it with an empty Find.
Find: (empty) Replace: /static/img/ Regex: off Before:  After:  Absolute URLs untouched: Before:  After: 
Regex to normalise a variable path
Paths had differing leading folders but all end in images/...; capture and re-root them.
Find: ^.*/(images/.+)$ Replace: /$1 Regex: on Before:  After: 
Fix a reference-style image definition
Only the definition line holds the path, so that's what you repair.
Find: old-assets/ Replace: assets/ Regex: off Before: ![Diagram][d1] [d1]: old-assets/diagram.png After: ![Diagram][d1] [d1]: assets/diagram.png
Edge cases and what actually happens
Broken because the URL is absolute and 404s
Not matchedIf the broken reference is an absolute http(s):// URL, the tool skips it — it only repairs relative paths. Edit the host by using that host as the Find substring (it still counts as relative-aware text replacement only when Find matches; absolute paths are bypassed by the apply step), or fix the asset at the host.
Image has an un-encoded space
Not matchedA space in the path stops the inline match. Replace the space with %20 (e.g. via another pass) before repairing, or the rewriter won't see that image.
Renamed individual file, not a folder
Use exact FindPrefixing won't help a single renamed file. Put the old filename in Find and the new one in Replace for a precise swap.
Find fragment also appears in a working path
CautionLiteral mode replaces every occurrence, so a too-broad Find can alter paths that were fine. Make Find specific (include a folder boundary like a trailing /) and re-validate after.
Regex only fixes the first match
By designRegex mode replaces the first match per path. For repeated literal fragments, use literal mode which replaces all occurrences.
Invalid regex
ErrorA malformed pattern throws when compiled and the run fails. Escape dots (\.) and double your backslashes when typing the pattern.
Still broken after rewrite
Re-validateIf the validator still flags references, the new path may also be wrong, or the asset file genuinely doesn't exist at the destination. Confirm the file is present where the rewritten path points.
Document over the size limit
RejectedFree caps at 1 MB / 500,000 characters. Split the file or upgrade before repairing very large documents.
Several files to fix
Single onlyProcess one document per run. Merge first, or repeat the fix per file.
Frequently asked questions
How do I find which image paths are broken?
Run the document through the link validator first — it reports references that don't resolve. Then bring the broken fragment here and rewrite it.
An asset folder was renamed — how do I fix every reference?
Put the old folder name in Find (e.g. old-assets/) and the new one in Replace (e.g. assets/). Literal mode swaps every occurrence across the file in one pass.
My images lost their base path entirely — what now?
Leave Find empty and put the correct base (e.g. /static/img/) in Replace. It's prepended to each relative path, restoring the base without touching absolute URLs.
Can it fix paths with a wrong `../` traversal?
Yes. Set Find to ../ and Replace to the correct prefix (or empty) to strip or rewrite the stale traversal across the document.
Will a broad Find accidentally change correct paths?
It can — literal mode replaces every occurrence. Make Find specific by including a boundary like a trailing slash, then re-run the validator to confirm only the intended paths changed.
Does it repair reference-style image definitions?
Yes. The path lives in the [id]: path definition line, and that line is rewritten alongside inline images.
Why didn't one of my broken images get fixed?
Likely it's either an absolute URL (skipped by design) or its path contains an un-encoded space or angle brackets, which the matcher doesn't recognise. Encode spaces as %20 and use the plain  form.
Can regex handle paths that break differently per file?
Yes. Tick Treat Find as regex, capture the stable part with a group, and reference it with $1 in Replace. Remember it replaces only the first match per path.
How do I confirm the fix worked?
Re-run the link validator on the output. If references still fail, the destination path may be wrong or the asset isn't where you pointed it.
Does it touch the actual image files?
No — it only edits text references. If an image is genuinely missing, you still need to restore or move the file itself.
What's the size limit for recovery jobs?
Free is 1 MB / 500,000 characters; Pro 10 MB / 5,000,000; Pro-media 50 MB / 20,000,000; Developer 500 MB / unlimited.
Can I fix many documents at once?
This tool runs one file per pass. Combine documents with the merger, repair the result, then split again if needed.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.