How to add a deployment prefix to markdown image paths
- Step 1Pick the environment base — Decide the prefix for this build — e.g.
https://staging-cdn.example.com/orhttps://cdn.example.com/, plus any sub-path like/docs/. - Step 2Load the source Markdown — Paste or upload the authored file, which should use relative image paths as the source of truth.
- Step 3Prefix with empty Find — Leave Find empty and put the environment base in Replace to prepend it to every relative path.
- Step 4Or remap between environments — If the doc already carries a base, set Find to the old host and Replace to the new one for an environment swap.
- Step 5Run the rewrite — Click Run Image Paths in the browser, or POST to the
md-image-path-rewriterendpoint via the local runner from your pipeline. - Step 6Feed the output to the build — Download (or capture the runner output) and pass the prefixed Markdown to your static-site generator for this environment.
Per-environment settings
Same source document, different prefix per build target.
| Build target | Find | Replace | Regex |
|---|---|---|---|
| Local preview | empty | / | off |
| Staging | empty | https://staging-cdn.example.com/ | off |
| Production | empty | https://cdn.example.com/ | off |
| Sub-path deploy | empty | /docs/assets/ | off |
| Swap staging→prod host | staging-cdn.example.com | cdn.example.com | off |
Browser vs API run
The rewrite is identical in both; choose based on whether it's interactive or part of a pipeline.
| Context | How | Output |
|---|---|---|
| Interactive | Paste/upload, set options, click Run | Markdown in read-only panel; Copy or Download |
| CI/CD | POST to the local runner for the slug with {find, replace, regex} | Rewritten Markdown text, original filename preserved |
| Same logic | Both call rewriteImagePaths | Byte-identical results for the same inputs |
Plan limits (markdown family)
Size, character, and file-count ceilings by 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
Deployment recipes. The source document stays relative; each build applies its own prefix.
Production build prefix
Empty Find prepends the production CDN base to every relative image.
Find: (empty) Replace: https://cdn.example.com/ Regex: off Before:  After: 
Staging build prefix from the same source
Run the same source file with the staging base for the staging deploy.
Find: (empty) Replace: https://staging-cdn.example.com/ Regex: off Before:  After: 
Sub-path deployment base
Docs served under /docs/ need that segment in front of every asset path.
Find: (empty) Replace: /docs/assets/ Regex: off Before:  After: 
Swap staging host for production
If a doc already carries the staging host, swap just the host with literal find/replace.
Find: staging-cdn.example.com Replace: cdn.example.com Regex: off Before:  After:  Note: absolute URLs are skipped by the rewriter, so host-only swaps on already-absolute paths are NOT applied — keep the source relative and prefix per environment instead.
API call shape via the local runner
The pipeline POSTs the file and options to the runner; the response is the rewritten Markdown.
POST 127.0.0.1:<runner-port>/v1/tools/md-image-path-rewriter/run
{
"text": "",
"options": { "find": "", "replace": "https://cdn.example.com/", "regex": false }
}
->
Edge cases and what actually happens
Source already has an absolute base
Host swap not appliedThe rewriter skips absolute http(s):// and // paths, so a find/replace that targets a host won't run on already-absolute URLs. Keep the authored source relative and prefix per environment for predictable results.
Double prefix from running twice
AvoidablePrefixing relative paths twice yields base/base/.... Always prefix from the relative source, not from an already-prefixed build artifact.
Forgot the trailing slash on the base
CautionAn empty-Find prefix is concatenated verbatim, so https://cdn.example.com (no slash) + assets/x.png becomes https://cdn.example.comassets/x.png. Include the trailing /.
Path with spaces
Not matchedUn-encoded spaces end the inline match. Ensure authored paths are URL-safe (use %20) so every image is prefixed.
Regex first-match-only
By designRegex mode replaces only the first match per path; use literal mode for replace-all of a repeated fragment.
Invalid regex in CI
ErrorA bad pattern throws at compile time and fails the run — surface the error in your pipeline logs and fix the escaping (double backslashes, escaped dots).
Build doc exceeds char limit
RejectedFree is capped at 500,000 characters / 1 MB. Use a higher tier or split the doc for very large build inputs.
Batch of docs in one build
Single per runEach run handles one file. Loop the runner call per file, or merge then re-split around the rewrite step.
Frequently asked questions
How do I prefix images per environment?
Leave Find empty and put the environment base (e.g. https://cdn.example.com/) into Replace. Run the same relative source once per environment with its own base.
Should I keep the authored source relative?
Yes. Relative paths are the safe source of truth — the rewriter prefixes them per build. If the source is already absolute, host swaps are skipped because absolute URLs are bypassed.
Can I run this in CI/CD?
Yes. The same rewriteImagePaths logic is exposed via the server engine, so you can POST {text, options:{find, replace, regex}} to the md-image-path-rewriter endpoint through the local runner from a build step.
Will browser and API output match?
Yes — both paths call the identical rewrite function, so the same input and options produce byte-identical Markdown.
I forgot the trailing slash and URLs are mashed together — why?
Empty-Find prefixing concatenates exactly what you type. https://cdn.example.com + assets/x.png = https://cdn.example.comassets/x.png. Add the trailing / to the base.
What if I prefix the same file twice?
Relative paths get the base twice (base/base/...). Always prefix from the relative source, not from a previously-built artifact.
Can it apply a sub-path base like /docs/?
Yes — put /docs/assets/ (or whatever your base path is) in Replace with an empty Find, and every relative image picks up that segment.
Does it skip external images?
Yes. Any http://, https://, //, or data: reference is left untouched, so third-party embeds aren't affected by your environment prefix.
Are reference-definition images prefixed too?
Yes. [id]: path definition lines are rewritten along with inline  images.
What size documents can the build step handle?
Free 1 MB / 500,000 characters; Pro 10 MB / 5,000,000; Pro-media 50 MB / 20,000,000; Developer 500 MB / unlimited.
Can one run process my whole docs folder?
No — it's one file per run. Loop the runner call across files in your pipeline, or merge with the merger and split afterward.
How do I verify the prefixed paths before deploy?
Run the output through the link validator against the target host, or preview the generated pages on staging before promoting to production.
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.