Marcos Silva
69 lines
1.8 KiB
Markdown
69 lines
1.8 KiB
Markdown
# 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
|
|
|
|
```python
|
|
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:
|
|
|
|
```xml
|
|
<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:
|
|
|
|
```xml
|
|
<ac:image ac:width="600">
|
|
<ri:attachment ri:filename="diagram.png" />
|
|
</ac:image>
|
|
```
|
|
|
|
Always set `ac:alt` for accessibility:
|
|
|
|
```xml
|
|
<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).
|