Show a diagram from GitHub in Confluence

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

To show a diagram from GitHub in Confluence, add the Github file (Capable) macro and pick the diagram file, such as a .mmd, .puml or .drawio file. The macro recognises the file type from its extension and draws the picture, not the source text, so the diagram on the page always matches the one in the repository.

#Before you start

  • You can edit the Confluence page, and you have a connected GitHub account if the repository is private.

  • The file has a diagram extension the macro recognises, for example .mmd or .mermaid (Mermaid), .puml or .plantuml (PlantUML), .drawio, .excalidraw, .bpmn, .dot (Graphviz), .d2, .dbml or .dsl (Structurizr).

#Steps

  1. Edit the page, type /Github and choose Github file (Capable).

  2. Select Select File, then find the repository in Search repositories or paste URL....

  3. Browse to the diagram file and select it. The preview shows the drawn diagram.

  4. Select Add to page and publish the page.

You can also paste the diagram file's github.com link straight into the editor.

#What happens next

The diagram is drawn on the page. Hover over it for its controls:

Control

What it does

Decrease size and Increase size

Zoom the diagram on the page. Not offered for draw.io and Excalidraw files.

Open diagram in modal

Opens the diagram full size in a window.

Toggle dark mode

Switches the diagram between light and dark, where the site allows it. Not offered for draw.io, Excalidraw and BPMN files.

Change the file on GitHub and the page shows the new diagram the next time it is viewed.

#If it does not work

  • The picker says This file type cannot be rendered: the extension is not one the macro knows. Rename the file or wrap the diagram in a Markdown file as a fenced code block.

  • The macro shows This file is empty: the file on that branch has no content. See Macro shows "This file is empty".

Diagrams as code, drawn where people look.