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​

Either the Apportunity Secure MCP Server, which lets an assistant such as Claude create Confluence pages directly. This is the easiest route: connect it once, then just ask.

Or an assistant that can call the Confluence REST API with your API token.

Either way, the assistant needs the technical instructions, which live on one page: AI Reference: Create a Confluence Page with a Diagram. Give it that link as part of your request.

How to ask​

Paste the reference link, then say what you want. That is the whole technique.

Use this guide: https://docs.apportunity.xyz/mermaid-diagrams/create-confluence-page-ai-prompt

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.

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-confluence-page-ai-prompt

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-confluence-page-ai-prompt

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-confluence-page-ai-prompt

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-confluence-page-ai-prompt

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 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.