Insert Diagrams from Git

Render text-based diagrams stored in your repositories directly on a page or work item.

Before you start

• Connect your Git account and ensure you can access the target repository.

• Confirm the diagram file contains valid syntax (e.g., Mermaid, PlantUML).

Commonly supported formats

• Mermaid: .mermaid, .mmd

• PlantUML: .plantuml, .puml

• Graphviz/DOT: .dot, .gv

• D2: .d2, DBML: .dbml, Excalidraw: .excalidraw, BPMN: .bpmn

• Blockdiag family: .blockdiag, .actdiag, .seqdiag, .packetdiag, .nwdiag, .rackdiag

• Vega/Vega-Lite: .vega.json, .vegalite.json

Insert steps

1. Insert the Github File macro

2. Connect/select your account and pick the repository and branch.

3. Browse to your diagram file and select it.

4. Preview and set the display title.

5. Insert to render the diagram.

Rendering tips

• Ensure the file’s syntax is valid; invalid content may show as text or an error.

• Large or complex diagrams may take longer to render.

Permissions

• Each viewer must have access to the repository to see the rendered diagram.

Troubleshooting

• Diagram won’t render: Validate syntax locally, then refresh.

• File not found: Verify the selected branch and path.