Library images and diagrams by reference
When you pick an image or diagram from the Capable library, Markdown writes a standard image line that points to a Capable reference:  for images, and the same line with the marker title capable-diagram for diagrams. It shows the asset's current version rather than a copy, so updates to the library item appear wherever you've used it.
Referenced diagrams are drawn the same way as diagrams you write directly in the document. The exceptions are draw.io, Excalidraw, BPMN and DMN, which use their own renderers.
Only images from the Capable library can be picked. If you select a page attachment or a stock image, the button is disabled and reads "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 who can edit the global library, which decides who can create global markdown templates. The same permission is shared with Diagrams, Images, Calendar and Search. |
Global settings → Egress domains | - | Images from approved domains load directly in the reader's browser instead of going through Capable, so they also load without a Capable sign-in. |
#Worth knowing
There are two Markdown macros: the document macro and the reference macro. There is no separate templates macro. Templates live in the library, and you use one either by copying it into the document macro (a snapshot that then drifts from the original) or by pointing the reference macro at it (a live link).
Readers who are not signed in see diagram code as a code block and images as their alt text. This is deliberate.
Diagrams are drawn on the server as static SVG, not in the reader's browser. Mermaid syntax newer than the version Capable supports can therefore fail, and Mermaid C4 diagrams are quietly converted to PlantUML C4.
Anonymous and unlicensed visitors see a notice instead of the Capable Markdown library page, though the macros still display for them.
Images you add to a document attach to the page that shows it, not to the document itself. Moving the document, or referencing it from another page, can break them.
Every admin control for Markdown is shared with other Capable apps. The Permissions tab in particular governs the whole global library, which Diagrams, Images, Calendar and Search also use.
#Limits that apply here
Library import truncation: long titles and descriptions are cut short when you drag page-owned markdown into the template library.
#Related
How it actually behaves.
