# Library images and diagrams by reference

Picking from the library writes ordinary markdown image syntax pointing at a Capable reference URL. !\[title\](.../assets/images/assets/<id>) for images, and the same shape with the marker title "capable-diagram" for diagrams. These render live at the asset's current version rather than copying the picture in. Referenced diagrams use the same Kroki pipeline as an inline fence, except drawio, excalidraw, bpmn and dmn, which use their native renderers. Only library (custom content) images can be picked. A page attachment or stock result leaves the button disabled and relabelled 'Not a library image'.

---

## Where you do it

| **Task**                                            | **Where**                                                                                            |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Write or edit the document body                     | The macro's Configure action, the maximize button on the rendered macro, or Edit on the library page |
| Insert an image or diagram from the Capable library | Editor toolbar → + → Image 'From library' or Diagram 'From library'                                  |
| Upload or paste an image into the document          | Editor toolbar → + → Image 'From upload', paste from the clipboard, or drop the file on the editor   |

---

## Settings that affect this

| **Setting**                      | **Where** | **What it does**                                                                                                                                                                                                             |
| -------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Global settings → Permissions    | \-        | Controls edit access to the GLOBAL asset store. Which is what governs who may create Global markdown templates. It is shared with diagrams, images, calendar and search because they all use one Confluence custom content t |
| Global settings → Egress domains | \-        | Customer-approved domains are fetched and loaded directly by the reader's browser instead of going through the Capable proxy, which also makes their images loadable without a Capable token. Customer-managed egress is ena |

---

## Worth knowing

* Exactly two Confluence macros exist and no more. There is no separate 'templates' macro. Templates are library assets, consumed either by copying into the document macro (a snapshot that then diverges) or by pointing the reference macro at one (a live link).
* Diagram fences and proxied images degrade to code blocks and alt text for logged-out readers. This is a deliberate degrade, not a failure.
* Diagrams are rendered server-side by Kroki as static SVG, not by mermaid.js in the browser, so mermaid syntax newer than Kroki's pinned version can fail; mermaid C4 is silently rewritten to PlantUML C4.
* Anonymous and unlicensed visitors get a marketing notice instead of the Capable Markdown library page, while the macros themselves still render for them.
* Images written into a document attach to the page that renders it, not to the document, so moving or referencing the document elsewhere can break them.
* Every admin control that affects markdown is a shared Capable settings surface; the Permissions tab in particular governs the whole global asset store shared with diagrams, images, calendar and search.

---

## Limits that apply here

* Library import truncation

---

## Related

[Image upload and pasteAnother part of how this works.](https://help.gocapable.com/markdown/image-upload-and-paste.html)

[GitHub-Flavored Markdown renderingAnother part of how this works.](https://help.gocapable.com/markdown/github-flavored-markdown-rendering.html)

[How it worksThe rest.](https://help.gocapable.com/markdown/how-it-works.html)

---

_How it actually behaves._