Skip to main content

Create Pages with AI

Ask an AI assistant to write a Confluence page, and get the diagrams already drawn on it.

Instead of writing a page, then adding a macro, then typing Mermaid syntax into it, you describe what you want once. The assistant creates the page with the explanation and the diagram in place, ready to read.

How it works​

The assistant puts the Mermaid source directly into the macro as it creates the page. Nobody has to open the page and fill the macro in afterwards, and the page exports to PDF and Word normally.

You can keep iterating. Ask for a change, the assistant rewrites the page, and everyone sees the new diagram. That stays true until somebody edits the diagram in Confluence, which hands ownership over to Confluence for good.

What you need​

Two things, both one-off:

  1. Apportunity: Mermaid Diagrams Macro for Confluence installed on your site. This is what draws the diagrams.
  2. Apportunity Secure MCP Server connected to your AI assistant. This is what lets it create Confluence pages for you. Follow its Getting Started guide once, and you are done.

The MCP server acts as you, with your own Confluence permissions, so your assistant can only touch pages you could edit yourself. You never share a password or an API token with it.

How to ask​

Paste a link to this page, then say what you want. That is the whole technique.

Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai

Create a Confluence page in the DEV space called "Checkout flow" that explains how an order moves from cart to confirmation, with a diagram of the steps.

The link matters. Without it the assistant does not know how this app stores diagrams, and will usually fall back to pasting Mermaid code into the page as plain text, which does not render.

You do not need to mention the MCP server in your prompt. The assistant will find it, and this page tells it to use it.

Example prompts​

Copy any of these and change the details.

A process, explained and drawn

Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai

Create a page in the OPS space called "Incident response" describing our escalation process: an alert fires, the on-call engineer triages it, and either resolves it or escalates to the team lead. Add a flowchart of the process and a short explanation above it.

Turn a conversation into a documented page

Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai

Summarise the architecture we just discussed into a Confluence page in the ARCH space, with a diagram of how the services talk to each other.

Document code you already have

Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai

Read the authentication module in this repository and create a Confluence page in the DEV space explaining the login flow, with a sequence diagram of the token exchange.

A page with several diagrams

Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-pages-with-ai

Create a page in the DEV space called "Release process" with three sections: branching, testing, and deployment. Give each section its own diagram and a paragraph explaining it.

Tips for better results​

  • Say which space, by name or key. It is the one thing the assistant cannot guess.
  • Ask it to send you the link when it is done, so you can check the result straight away.
  • Ask for the explanation too, not only the diagram. A diagram with a paragraph above it is far more useful than a diagram alone.
  • Say what kind of diagram if you have a preference, for example a sequence diagram or a Gantt chart. Otherwise the assistant picks one.
  • One diagram per idea. Several diagrams on a page is normal and encouraged; each one goes in its own macro with its own introduction.
  • Open the page and check it. If a diagram is wrong, ask the assistant to fix that section, or edit it yourself in the macro.

Changing a diagram afterwards​

Before anyone has edited it, just ask the assistant again.

Update the diagram on the "Checkout flow" page to include the refund path.

Once somebody has edited the diagram in Confluence, that edit wins and further requests to the assistant will not change what readers see. From then on, edit the diagram in Confluence: click the macro, change the source, and save. See Getting Started.

This is deliberate. A person's edit should never be silently overwritten by a regenerated page.

If something looks wrong​

What you seeWhat to do
The assistant says it cannot create pagesThe Confluence MCP server is not connected. Follow its Getting Started guide.
Mermaid code appears as plain text on the pageThe assistant did not follow this guide. Include the link in your request.
A grey box, or "app not found", where the diagram should beThe Mermaid Diagrams app is not installed on the site, or the assistant altered the extension-key below.
The macro appears but is emptyThe guest-params block was built wrongly. Ask the assistant to re-read this page and try again.
The diagram shows an error messageThe Mermaid syntax is invalid. Point the assistant at Diagram Syntax for AI.
Arrows missing, or a diagram cut shortThe > characters were not escaped. See the escaping table below.
Two diagrams show the same contentThe macros share a local-id. Each needs its own fresh UUID.
Updating the page no longer changes the diagramSomebody has edited that diagram in Confluence, so it is now owned by the page. Edit it in Confluence instead.

Instructions for your AI assistant​

Everything below is written for the assistant. You do not need to read it.

Use the Confluence MCP server​

Create the page with the confluence_create_page tool from the connected Confluence MCP server.

Do not write scripts, do not call the Confluence REST API directly, and do not ask the user for an API token or password. If the MCP server is not connected, say so and stop.

Insert the diagram macro​

confluence_create_page takes a space_key, a title, and content in Confluence Storage Format. Write the page as you normally would - headings, paragraphs, lists - and insert this block wherever a diagram belongs:

<ac:adf-extension><ac:adf-node type="extension"><ac:adf-attribute key="extension-type">com.atlassian.ecosystem</ac:adf-attribute><ac:adf-attribute key="extension-key">9d10a082-4d4e-4efa-996b-9c0170f3bfee/7a286cf2-9d8a-4c57-9bd2-102c413343b2/static/mermaid-macro</ac:adf-attribute><ac:adf-attribute key="local-id">PUT-A-FRESH-UUID-HERE</ac:adf-attribute><ac:adf-attribute key="parameters"><ac:adf-parameter key="local-id">PUT-A-FRESH-UUID-HERE</ac:adf-parameter><ac:adf-parameter key="guest-params"><ac:adf-parameter key="diagram">graph TD;
  A[Start] --&gt; B[End];</ac:adf-parameter><ac:adf-parameter key="size">medium</ac:adf-parameter></ac:adf-parameter></ac:adf-attribute></ac:adf-node></ac:adf-extension>

Only three things change per diagram:

WhatWhereNotes
A fresh UUIDlocal-id, in both placesGenerate a new one for every macro. The two must match.
The Mermaid sourceguest-params → diagramRequired.
The display heightguest-params → sizeOptional. One of small, medium, large, xlarge, full. Defaults to medium.

The long extension-key value is the same on every Confluence site. Copy it exactly.

Escape the diagram​

The diagram sits inside XML, so three characters must be escaped:

CharacterWrite it as
>&gt;
<&lt;
&&amp;

In practice this means arrows: --> is written --&gt;, and ->> is written -&gt;&gt;. Line breaks stay as real line breaks.

One diagram per macro​

A macro holds one diagram. For several diagrams on a page, insert several macros, each with its own fresh UUID and its own introduction.

Complete example​

A page with two diagrams, each introduced by a sentence:

<h2>Checkout flow</h2>
<p>The diagram below shows how an order moves from cart to confirmation.</p>
<ac:adf-extension><ac:adf-node type="extension"><ac:adf-attribute key="extension-type">com.atlassian.ecosystem</ac:adf-attribute><ac:adf-attribute key="extension-key">9d10a082-4d4e-4efa-996b-9c0170f3bfee/7a286cf2-9d8a-4c57-9bd2-102c413343b2/static/mermaid-macro</ac:adf-attribute><ac:adf-attribute key="local-id">d7c1f0a2-6b4e-4a1b-9c3d-2f8e5a7b1c40</ac:adf-attribute><ac:adf-attribute key="parameters"><ac:adf-parameter key="local-id">d7c1f0a2-6b4e-4a1b-9c3d-2f8e5a7b1c40</ac:adf-parameter><ac:adf-parameter key="guest-params"><ac:adf-parameter key="diagram">graph TD;
  A[Cart] --&gt; B{Payment OK?};
  B -- Yes --&gt; C[Confirm order];
  B -- No --&gt; D[Show error];</ac:adf-parameter><ac:adf-parameter key="size">large</ac:adf-parameter></ac:adf-parameter></ac:adf-attribute></ac:adf-node></ac:adf-extension>
<p>Payment authorisation itself involves three services:</p>
<ac:adf-extension><ac:adf-node type="extension"><ac:adf-attribute key="extension-type">com.atlassian.ecosystem</ac:adf-attribute><ac:adf-attribute key="extension-key">9d10a082-4d4e-4efa-996b-9c0170f3bfee/7a286cf2-9d8a-4c57-9bd2-102c413343b2/static/mermaid-macro</ac:adf-attribute><ac:adf-attribute key="local-id">4b90e7d1-2c35-49aa-8f16-71d0c3ab5e92</ac:adf-attribute><ac:adf-attribute key="parameters"><ac:adf-parameter key="local-id">4b90e7d1-2c35-49aa-8f16-71d0c3ab5e92</ac:adf-parameter><ac:adf-parameter key="guest-params"><ac:adf-parameter key="diagram">sequenceDiagram
  Shop-&gt;&gt;Gateway: authorise
  Gateway-&gt;&gt;Bank: verify
  Bank--&gt;&gt;Gateway: ok
  Gateway--&gt;&gt;Shop: approved</ac:adf-parameter><ac:adf-parameter key="size">medium</ac:adf-parameter></ac:adf-parameter></ac:adf-attribute></ac:adf-node></ac:adf-extension>

Pass that as content, along with the space key and a title.

Changing a diagram you created​

Update the page with confluence_update_page: read it, replace the Mermaid source inside guest-params, and write it back.

This works until somebody edits the diagram in Confluence. At that point the app stores the diagram with the page and takes ownership of it, and further changes to the page source are ignored.

Writing good pages​

  • Introduce each diagram with a sentence or two before it. A diagram with no explanation is hard to act on.
  • Split a diagram that is getting dense into two simpler ones rather than growing it.
  • Prefer large for flowcharts and sequence diagrams with more than about ten nodes, medium for small ones.
  • Keep each diagram's source to a reasonable size, roughly a page of text at most. The source travels inside the page, so very large diagrams make the page heavier for every reader.
  • For choosing a diagram type and writing correct syntax, follow Diagram Syntax for AI.