# Show a diagram from GitHub in Confluence

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"](https://help.gocapable.com/git/macro-shows-this-file-is-empty.html).

---

## Related

### [Github file](https://help.gocapable.com/git/github-file.html)

Every setting and what the macro shows.

### [Embed a GitHub file in Confluence](https://help.gocapable.com/git/embed-a-github-file-in-confluence.html)

Any file, picked or pasted.

### [Show a GitHub README in Confluence](https://help.gocapable.com/git/show-a-github-readme-in-confluence.html)

Markdown with diagrams inside.

### [Limits](https://help.gocapable.com/git/limits.html)

Size and type limits.

---

_Diagrams as code, drawn where people look._