Why the images break
An image in a Confluence page is an attachment on that page. The page body only references it, and the reference resolves to a URL like https://your-site.atlassian.net/wiki/download/attachments/123456/diagram.png.
That URL only works for someone logged in to your Confluence site who is allowed to see the page. Inside Confluence that's everyone reading, so you never notice. Outside it, a reader (or a build server, or a crawler) gets redirected to the Atlassian login page, and an <img> tag can't display a login page.
So you see broken images whenever the content leaves Confluence but the image references don't change:
- Markdown converters that read pages through the API and keep the attachment URLs as they are.
- Copy and paste from a Confluence page into another editor, which brings the URLs, not the files.
- A site or wiki you are retiring. Even links that worked for logged-in readers die when the Confluence site is closed.
- Migrations into Confluence can lose attachments too: Atlassian's own tracker has reports of "Attachment File Not Found" after moving to Cloud. If that's your problem, re-check the attachment counts before you go further.
Step 1: get the image files out
You need the actual files, because nothing outside Confluence can fetch them through the login. There are two ways:
- HTML space export. In the space, go to Space settings and export the space as HTML. The ZIP contains a page per HTML file plus the attachment files, in folders keyed by page ID (the files themselves may be named by attachment ID rather than their original name). This is the easiest source for a migration, because the exported HTML already points at those local files.
- The REST API. List each page's attachments (
/wiki/rest/api/content/<pageId>/child/attachment) and download each one using an Atlassian API token. Use this if your converter already produced Markdown with Confluence URLs in it and you only need the files.
Atlassian's own advice for pulling every attachment in a space is the same pair of options. Whichever you use, count the files against the attachment listing: migrations are known to drop some without an error.
Step 2: convert the pages
Turn the exported HTML into Markdown with the tool you already use for the migration, for example pandoc -f html -t gfm-raw_html page.html -o page.md. The -raw_html part matters: Confluence puts sizes and classes on its images, and without it pandoc keeps them as HTML <img> tags instead of Markdown images. Check one page: the image links should now be Markdown images with local paths into the export folder, not atlassian.net URLs.
Local paths work on your machine and break everywhere else: on a docs site whose build doesn't copy the folder, in a GitHub wiki, in Notion, in an email. Step 3 replaces them with real URLs.
Step 3: re-host the images and rewrite the links
This script walks a folder of Markdown files, finds every image that points at a local file, uploads each file to PixelVault once, and rewrites the link to the permanent img.pixelvault.dev URL. It needs Node 18 or later and an API key from a free account:
Before you run it: Confluence attachments are login-only, and the new URLs are public: anyone who has a link can open the image. That is what makes them work outside Confluence, but it is a change in who can see them. If some pages hold confidential material, run the script only on the folders you are fine sharing that way.
- It edits files in place, so run it on a copy (or a git branch) of the converted export.
- It keeps a
rehosted.jsonmap, and uploads withdedupe, so you can stop and re-run it, and an image used on ten pages is uploaded once. - It handles Markdown image syntax. If your converter left raw
<img src>tags, convert those first or extend the pattern. - Each image can be up to 5 MB on the free plan (10 MB on Starter, 15 MB on Pro). Files it can't upload are listed and skipped, not lost.
When it's done, search the output for three things:
<img: HTML image tags the script doesn't rewrite.](attachments/: a local image that failed to upload. The script printed why.atlassian.net/wiki/download: an image the converter linked remotely instead of exporting. The script leaves URLs alone, so turn these into local paths first: download the files with the API as in Step 1, into anattachments/folder next to the Markdown, then point the links at them and run the script again:
If an agent is doing the migration
Content migrations are increasingly run by coding agents, and they tend to stop at "the Markdown converted", because nothing fails. Give the agent the three steps above as the definition of done, plus the final atlassian.net search. With the PixelVault MCP server connected it can upload the files itself.
Only a handful of images? Download them from Confluence while logged in and turn each into a link with the image to URL tool. No signup to try it; save them to a free account to keep them.
Same problem, other sources
- GitHub private-repo attachments expire minutes after they are rendered.
- Notion API image URLs expire after an hour, and Notion exports leave you with local paths.
- imgbox and Imgur embeds break when the host blocks or drops them.