Attachments

Attachments live on a page and are referenced by filename. They survive page moves and template changes, but they do not survive page deletion.

Upload via mcp-atlassian

mcp__atlassian.confluence_upload_attachment(
    pageId=…,
    filePath="path/to/file.png",
    comment="optional version note",
)

Returns a metadata object including the download URL. Use that URL inside the page body, not a local file path.

Reference in the body

By attachment filename:

<ac:link>
  <ri:attachment ri:filename="diagram.png" />
  <ac:plain-text-link-body><![CDATA[diagram]]></ac:plain-text-link-body>
</ac:link>

As an inline image:

<ac:image ac:width="600">
  <ri:attachment ri:filename="diagram.png" />
</ac:image>

Always set ac:alt for accessibility:

<ac:image ac:width="600">
  <ri:attachment ri:filename="diagram.png" />
  <ac:alt>Sequence diagram of the order → inventory → shipment flow.</ac:alt>
</ac:image>

What NOT to do

Don't paste base64 PNG into the body. The page editor can't replace it without re-rendering the whole page; it bloats the storage body; the page cannot be reviewed by lint.
Don't link to a public CDN. BASS pages are private; CDN URLs leak and break on access-controlled spaces.
Don't re-upload the same file under a new name. Confluence deduplicates by hash within a page, but the editor doesn't surface duplicates well.

Versioning

Attach with a version suffix (diagram-v2.png) when updating. Confluence keeps the old version in the attachments list and the page body continues to reference the filename; change the filename in the body to point at the new version.

Cleanup

Pages with stale attachments show up in the space's attachment report. When removing a diagram, also remove the attachment (do not leave orphaned files on the page).

1.8 KiB Raw Blame History