Slack, email, Confluence, and Notion
How to put a Plotwork diagram where a picture is wanted outside a repository: a PNG for a chat or an email, and paste-ready text for Confluence and Notion. Nothing here needs an account with those services, a token, or a paid API.
- Slack
- Confluence
- Notion
TL;DR
| Where | What to use | How |
|---|---|---|
| Slack, Teams, email | A PNG | Open pngUrl from the agent's answer. The page draws the diagram and saves the PNG. Attach the file. |
| Anywhere that takes an image link | The hosted SVG link | Ask the agent to publish the diagram (publish_diagram), and paste the link. |
| Confluence Cloud | Wiki markup | npx @buun_group/plotwork export diagram.md --format confluence-wiki, then Insert, then Markup. |
| Confluence through its REST API, or a page source editor | Storage format | npx @buun_group/plotwork export diagram.md --format confluence. |
| Notion | Markdown | npx @buun_group/plotwork export diagram.md --format notion --image <hosted link>, then paste. |
| Does Plotwork draw the PNG on a server? | No | The PNG is drawn in the browser that opens the link. Plotwork's servers never see the diagram. |
| Does Plotwork publish to Confluence or Notion for me? | No | Doing so would mean storing a token for your workspace. Plotwork stores none. You paste. |
1. A PNG for a chat or an email
Every valid answer of draw_diagram, draw_from_pattern, and convert_mermaid has two links:
| Field | What opening it does |
|---|---|
viewUrl | Shows the diagram in the browser. See Viewing diagrams. |
pngUrl | The same link with &download=png at the end. It shows the diagram and saves it as a PNG, in the theme the page shows, at twice its size. |
pngUrl is a link to open, not an image address to embed: the PNG is made in your browser from the source in the link, after the #, which a browser never sends to a server. Open it, then attach the file it saved. &download=svg saves the SVG the same way.
A diagram too large for a link has neither field, and the answer says why; publish it instead.
2. A hosted link
A published diagram has a fixed address on cdn.plotwork.dev, an SVG that any page, wiki, or chat that shows images can load. Ask the agent to publish the diagram, or see Hosted diagrams. Use the link as the image of the exports below, and the wiki fetches the picture itself.
A picture link shows one drawing. For a page that should keep up with edits, publish with an alias and use the stable link instead: it always shows the latest version published under that name. See Links that always show the latest version.
3. Confluence
The command line writes the picture and the diagram's source, folded in an expand block under it, so the page keeps what the picture was drawn from.
| Format | Flag | Where it goes |
|---|---|---|
| Wiki markup | --format confluence-wiki | Confluence Cloud: in the editor choose Insert, then Markup, pick Confluence wiki, and paste. |
| Storage format (XHTML) | --format confluence | The body of a page sent to the Confluence REST API with the representation storage, or a page source editor. |
Where the picture comes from:
| You pass | The text refers to | You do |
|---|---|---|
--image <hosted link> | The link | Paste. Confluence loads the picture from the link. |
| Nothing | An attachment named after the diagram | The command writes the SVG beside the text. Attach it to the page first (Insert, then Files and images), then paste. |
The picture is never embedded in the text. Confluence's storage format names an image only by attachment or by address, and it does not show an image written into a page as a data: address.
npx @buun_group/plotwork export docs/architecture.md --format confluence-wiki --image https://cdn.plotwork.dev/d/<token>.svgThe command reads the first diagram of the file: a diagram file, or the first diagram fence of a Markdown file. --no-source leaves the source out, and --theme dark writes the dark picture.
4. Notion
npx @buun_group/plotwork export docs/architecture.md --format notion --image https://cdn.plotwork.dev/d/<token>.svgPaste the text into a page. Notion turns the image link into an image block and the source into a code block. With a stable link as the --image, the image block shows each new version the next time the page loads. To add only the picture, type /image, choose Embed link, and paste the link. Without --image, the command writes the SVG beside the text: paste, delete the broken image, and drag the SVG onto the page in its place, because Notion cannot load a file named in pasted text.
5. Why there is no direct publishing
Writing to a Confluence or Notion workspace needs an OAuth app registered with each service, a server that holds every person's access token, and a way to refresh and revoke those tokens. Plotwork holds no such token and keeps no diagram content, so you paste the text yourself. The command line runs on your machine and sends nothing.
See also
| Page | Why |
|---|---|
| Viewing diagrams | What the view link is and what it sends |
| Hosted diagrams | Links that load as images anywhere |
| Keep diagrams in sync in CI | The command line, and the check for pull requests |
| Privacy policy | What Plotwork stores, and what it does not |