Confluence Graphviz Diagrams: DOT Language FAQ & Examples

Graphviz has been the backbone of automated graph visualization for over three decades. Originally developed at AT&T Labs, it powers dependency graphs in build systems, call graphs in profilers, and database schemas in ORMs -- anywhere that diagrams need to be generated from structured data rather than drawn by hand. Graphviz Charts for Confluence brings that same engine directly into your Confluence pages, letting you write DOT language descriptions and get polished, auto-laid-out diagrams without leaving your wiki.

This FAQ answers the most common questions teams ask when getting started with Graphviz Charts for Confluence. Whether you are evaluating the app for the first time, migrating from a manual diagramming tool, or deciding between Graphviz and Mermaid, you will find practical answers below along with copy-paste DOT examples you can try immediately.

What is Graphviz and how does it work in Confluence?

Graphviz is an open-source graph visualization software suite that takes text descriptions of graphs and produces diagrams as output. It is not a drawing tool -- you do not drag shapes or connect boxes with a mouse. Instead, you describe the structure of your graph in plain text using the DOT language, and Graphviz's layout algorithms compute where every node and edge should appear. The result is a clean, consistent diagram that scales to hundreds of nodes without manual adjustment.

Graphviz Charts for Confluence wraps this engine in a Confluence macro. You insert the macro by typing /Graphviz Charts for Confluence in the Confluence editor, write or paste your DOT code into the macro body, and click save. The app renders the diagram inline on the page. You can also click the edit icon on the macro to configure it further, and you can use Confluence's built-in alignment options to position the rendered diagram within the page layout.

The app supports Confluence Cloud and Confluence Data Center. Because the DOT code is stored as plain text inside the macro, it is fully version-controlled through Confluence's page history. Every edit to the graph is tracked, and you can diff changes between versions just like any other page content.

For the full setup and configuration details, see the Graphviz Charts for Confluence usage guide.

What is the DOT language and how do I get started?

DOT is the primary language for describing graphs in Graphviz. It is a declarative, plain-text format where you define nodes, edges, and their properties, and the layout engine handles positioning and routing. Learning DOT takes minutes -- the syntax is intentionally minimal.

Here is the smallest possible directed graph:

digraph {
  A -> B -> C
}

This creates three nodes (A, B, C) connected by directed edges with arrowheads. The digraph keyword indicates a directed graph. For undirected graphs (no arrowheads), use graph and double-dash edges:

graph {
  A -- B -- C
}

You can add labels, shapes, and styling attributes to nodes and edges using square brackets:

digraph {
  rankdir=LR
  Start [label="User Request", shape=box, style=filled, fillcolor="#E8F5E9"]
  Validate [label="Validate Input", shape=box]
  Decision [label="Valid?", shape=diamond]
  Process [label="Process Request", shape=box, style=filled, fillcolor="#E3F2FD"]
  Error [label="Return Errors", shape=box, style=filled, fillcolor="#FFEBEE"]

  Start -> Validate -> Decision
  Decision -> Process [label="Yes"]
  Decision -> Error [label="No"]
}

Key DOT syntax elements you will use regularly:

• digraph -- directed graph with arrow-headed edges. Edges use ->.
• graph -- undirected graph with plain-line edges. Edges use --.
• rankdir -- controls layout direction. TB (top to bottom, default), LR (left to right), BT (bottom to top), RL (right to left).
• [label="text"] -- sets the display label for a node or edge. Without a label, the node ID is used.
• [shape=...] -- sets node shape. Common values: box, ellipse, diamond, circle, record, plaintext.
• [style=filled fillcolor="#hex"] -- fills the node background with a color.
• [color="#hex"] -- sets the border or edge color.

The official DOT language reference is available at graphviz.org/doc/info/lang.html, and the Graphviz layout documentation is at graphviz.org/docs/layouts/.

What types of diagrams can I create with Graphviz Charts?

Graphviz is not limited to a single diagram type. Through different graph kinds and layout engines, it covers a wide range of visualization needs.

Directed graphs (digraph)

Directed graphs are the most common Graphviz output. Every edge has a direction indicated by an arrowhead, making them ideal for flowcharts, dependency trees, data pipelines, and state machines. The dot layout engine (the default) produces ranked, hierarchical layouts that minimize edge crossings and produce clean, top-down or left-right diagrams.

digraph dependencies {
  rankdir=TB
  node [shape=box, style=rounded]

  APIGateway [label="API Gateway"]
  AuthSvc [label="Auth Service"]
  UserSvc [label="User Service"]
  OrderSvc [label="Order Service"]
  DB [label="Database", shape=cylinder]
  Cache [label="Redis Cache", shape=parallelogram]

  APIGateway -> AuthSvc
  APIGateway -> UserSvc
  APIGateway -> OrderSvc
  UserSvc -> DB
  OrderSvc -> DB
  UserSvc -> Cache
  OrderSvc -> Cache
}

This example shows a microservices dependency graph. Notice how the dot engine automatically layers the nodes so that dependencies flow downward, making the architecture immediately readable.

Undirected graphs (graph)

Undirected graphs use plain lines without arrowheads. They are useful for network topologies, social graphs, relationship maps, and any scenario where directionality does not matter. The neato and fdp layout engines work well for undirected graphs, producing spring-model layouts that cluster related nodes together.

Record structures

Graphviz supports record-based node shapes that display fields in a structured, table-like format. This is particularly useful for entity schemas, class diagrams, and data model documentation where you want to show the internal structure of a node.

digraph data_model {
  rankdir=LR
  node [shape=record]

  User [label="{User|+ id: int\l+ name: string\l+ email: string\l+ created_at: timestamp\l}"]
  Order [label="{Order|+ id: int\l+ user_id: int\l+ total: decimal\l+ status: enum\l}"]
  Product [label="{Product|+ id: int\l+ name: string\l+ price: decimal\l+ stock: int\l}"]

  User -> Order [label="has many"]
  Order -> Product [label="contains"]
}

The \l characters in record labels produce left-aligned text within each field row. This DOT code renders three entity boxes with their field lists and relationships -- a format that is immediately recognizable to anyone who has worked with database schemas or UML class diagrams.

Layout engines

Graphviz Charts for Confluence supports the full set of Graphviz layout engines:

Engine	Best for	Layout style
dot	Hierarchical and directed graphs	Top-down ranked layers (default)
neato	Undirected graphs, spring model	Force-based positioning
fdp	Large undirected graphs	Force-directed placement
sfdp	Very large graphs	Scalable force-directed (handles thousands of nodes)
circo	Circular relationships	Circular arrangement
twopi	Radial layouts	Concentric circles around a root node

Choose the engine that matches your graph structure. For most flowcharts and dependency diagrams, dot produces the clearest results. For network topologies with no inherent hierarchy, neato or fdp often work better.

How does Graphviz auto-layout compare to manual diagramming?

The single biggest advantage Graphviz offers over visual drag-and-drop tools is automatic layout. When you draw a diagram by hand -- whether in Excalidraw, draw.io, or a desktop application -- you spend significant time positioning nodes, routing edges, and adjusting spacing every time the diagram changes. With Graphviz, you describe the relationships and the engine handles all visual positioning.

This matters most when diagrams grow large. A dependency graph with 50 nodes and 80 edges takes hours to lay out manually and is nearly impossible to keep tidy as nodes are added or removed. Graphviz recomputes the layout in milliseconds, producing a consistent, readable diagram every time. Edge crossings are minimized, spacing is uniform, and the hierarchical structure is preserved without manual intervention.

Auto-layout also eliminates the "drift" problem that plagues manually maintained diagrams. When different team members edit a drag-and-drop diagram over months, the layout gradually degrades -- nodes get nudged, spacing becomes inconsistent, and the diagram loses its original clarity. With text-based DOT code, the layout is always computed fresh from the current graph definition, so it stays clean regardless of how many people contribute changes.

The tradeoff is control. Graphviz decides where nodes go, and you cannot manually override specific positions (though you can influence the layout through rank constraints, group attributes, and rankdir settings). For teams that need pixel-perfect placement -- for example, architecture diagrams that must match a specific visual template -- a visual tool like Excalidraw Plus or Diagram Duo may be more appropriate.

Can I style and customize Graphviz diagrams in Confluence?

Graphviz provides extensive styling capabilities through DOT attributes. You can customize nearly every visual aspect of nodes and edges without touching any CSS or external styling.

Node styling. Control the appearance of individual nodes or set global defaults:

digraph {
  // Global default for all nodes
  node [shape=box, style="rounded,filled", fillcolor="#F5F5F5", color="#333333",
        fontname="Helvetica", fontsize=11]

  // Per-node overrides
  Start [fillcolor="#4CAF50", fontcolor="white", label="Start"]
  Process [fillcolor="#2196F3", fontcolor="white", label="Process Data"]
  End [fillcolor="#F44336", fontcolor="white", label="Complete"]

  Start -> Process -> End
}

Edge styling. Control line color, thickness, style, and labels:

digraph {
  A -> B [label="sync", color="#2196F3", penwidth=2]
  B -> C [label="async", style=dashed, color="#FF9800"]
  C -> D [label="retry", style=dotted, color="#F44336", dir=both]
}

Available style attributes include:

• color -- border/edge color (hex or named color)
• fillcolor -- node fill color (requires style=filled)
• fontname, fontsize, fontcolor -- text styling
• penwidth -- edge or border thickness
• style -- filled, rounded, dashed, dotted, bold, or combinations like "rounded,filled"
• shape -- box, ellipse, diamond, circle, hexagon, octagon, parallelogram, trapezium, cylinder, record, and more
• arrowhead / arrowtail -- arrow shape (normal, vee, dot, odot, empty, inv, and others)
• dir -- edge direction (forward, back, both, none)

Graphviz Charts for Confluence also respects Confluence's editor alignment options. Once the macro is on the page, you can use the alignment toolbar to center, left-align, or right-align the rendered diagram. This works the same way as aligning images or tables in Confluence.

How does Graphviz Charts compare to Mermaid for Confluence diagrams?

Both Graphviz Charts and Mermaid Plus render diagrams from text-based syntax inside Confluence macros. They share the benefits of version control, diffability, and no-external-tool dependency. But they have different strengths.

Where Mermaid excels

Mermaid supports a broader range of diagram types out of the box: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, pie charts, mindmaps, timelines, Git graphs, C4 architecture diagrams, Sankey diagrams, and more. If you need to create a sequence diagram showing API interactions between services, Mermaid's sequenceDiagram syntax is purpose-built for that. Graphviz has no equivalent.

Mermaid's syntax is also simpler for common cases. A basic flowchart in Mermaid is more concise than the same flowchart in DOT:

flowchart TD
  A --> B --> C

versus:

digraph {
  rankdir=TB
  A -> B -> C
}

For teams already using Mermaid across tools (GitHub, GitLab, Notion, Obsidian), staying in the Mermaid ecosystem reduces context-switching.

Where Graphviz excels

Graphviz produces superior layouts for large, complex graphs. The dot engine's hierarchical ranking algorithm handles graphs with hundreds of nodes and produces more readable results than Mermaid's layout engine at that scale. If you are visualizing a build dependency graph with 200 packages, or a database schema with 80 tables, Graphviz will produce a cleaner diagram.

Graphviz also supports record-based node structures for showing entity fields -- a feature Mermaid does not offer in its flowchart syntax. For data model documentation where you want to display column names and types inside each table node, Graphviz is the right choice.

Graphviz offers more layout engines (dot, neato, fdp, sfdp, circo, twopi), giving you more control over how different graph structures are visually arranged. Mermaid uses a single layout engine with direction flags.

Quick comparison

Criteria	Graphviz Charts	Mermaid Plus
Diagram types	Directed graphs, undirected graphs, records	15+ types including sequence, Gantt, pie, mindmap, C4
Layout engines	6 (dot, neato, fdp, sfdp, circo, twopi)	1 with direction flags
Large graph handling	Excellent -- optimized for 100+ nodes	Good up to ~100 nodes
Record/node structures	Yes -- field-level detail in nodes	No -- labels only
Syntax simplicity	Moderate -- more verbose	Simple -- concise for common cases
Learning curve	DOT language has more attributes to learn	Easier for basic diagrams
Ecosystem	Used in build tools, profilers, ORMs	Used in GitHub, GitLab, Notion, Obsidian

Recommendation: Use Mermaid Plus for flowcharts, sequence diagrams, Gantt charts, and quick diagrams where syntax simplicity matters. Use Graphviz Charts for large dependency graphs, network topologies, data model diagrams with field-level detail, and any scenario where automatic layout quality is the top priority. Read the full usage guide to get started with Graphviz Charts.

Copy-paste DOT examples for Confluence

Here are three ready-to-use DOT examples you can paste directly into the Graphviz Charts for Confluence macro. Each demonstrates a different graph type and styling approach.

Example 1 -- CI/CD pipeline flowchart

digraph ci_pipeline {
  rankdir=LR
  node [shape=box, style="rounded,filled", fillcolor="#E3F2FD", fontsize=11]

  Commit [label="Git Commit", fillcolor="#4CAF50", fontcolor="white"]
  Build [label="Build", fillcolor="#2196F3", fontcolor="white"]
  UnitTest [label="Unit Tests", fillcolor="#2196F3", fontcolor="white"]
  Integration [label="Integration Tests", fillcolor="#2196F3", fontcolor="white"]
  Staging [label="Deploy Staging", fillcolor="#FF9800", fontcolor="white"]
  Approval [label="Manual Approval", shape=diamond, fillcolor="#FFF9C4", fontcolor="#333"]
  Production [label="Deploy Production", fillcolor="#F44336", fontcolor="white"]

  Commit -> Build -> UnitTest -> Integration -> Staging -> Approval -> Production
}

This example uses left-to-right layout (rankdir=LR) to show a CI/CD pipeline as a linear flow. Color coding distinguishes source control (green), build/test stages (blue), deployment (orange), approval gates (yellow), and production (red).

Example 2 -- Network topology (undirected graph)

graph network {
  layout=neato
  node [shape=circle, style=filled, fontsize=9]

  Router [fillcolor="#4A90D9", fontcolor="white"]
  Firewall [fillcolor="#F44336", fontcolor="white"]
  Switch1 [fillcolor="#FF9800", fontcolor="white"]
  Switch2 [fillcolor="#FF9800", fontcolor="white"]
  Server1 [fillcolor="#4CAF50", fontcolor="white"]
  Server2 [fillcolor="#4CAF50", fontcolor="white"]
  Server3 [fillcolor="#4CAF50", fontcolor="white"]
  DB [fillcolor="#9C27B0", fontcolor="white", label="Database"]

  Router -- Firewall
  Firewall -- Switch1
  Firewall -- Switch2
  Switch1 -- Server1
  Switch1 -- Server2
  Switch2 -- Server3
  Switch2 -- DB
  Server1 -- DB [style=dotted]
  Server2 -- DB [style=dotted]
}

This uses the neato layout engine for a spring-model arrangement that clusters connected nodes together naturally. The undirected edges (--) indicate bidirectional network connections.

Example 3 -- Data model with record structures

digraph schema {
  rankdir=LR
  node [shape=record, fontsize=10]

  Customer [label="{Customer|+ id: UUID\l+ name: string\l+ email: string\l+ tier: enum\l}"]
  Subscription [label="{Subscription|+ id: UUID\l+ customer_id: UUID\l+ plan: string\l+ status: enum\l+ expires_at: date\l}"]
  Invoice [label="{Invoice|+ id: UUID\l+ subscription_id: UUID\l+ amount: decimal\l+ paid_at: timestamp\l}"]
  Plan [label="{Plan|+ id: UUID\l+ name: string\l+ price: decimal\l+ features: json\l}"]

  Customer -> Subscription [label=" 1:N "]
  Subscription -> Invoice [label=" 1:N "]
  Plan -> Subscription [label=" 1:N "]
}

This record-structure diagram shows a SaaS billing data model with four entities and their field definitions. Each entity box displays its columns, making the schema immediately understandable without a separate data dictionary.

How to insert a Graphviz diagram in Confluence

Follow these steps to add a Graphviz diagram to any Confluence page:

1. Open the Confluence editor by editing an existing page or creating a new one.
2. Insert the macro by typing /Graphviz Charts for Confluence in the editor. Select Graphviz Charts for Confluence from the dropdown.
3. Write or paste your DOT code into the macro body. You can use any of the examples above as a starting point.
4. Click the edit icon on the macro to configure layout engine, alignment, and other settings.
5. Save the macro and publish the page. The diagram renders inline for all page viewers.

The macro stores your DOT code as plain text, so it is fully searchable through Confluence's full-text search and tracked in page history.

Frequently Asked Questions

Can I use Graphviz Charts alongside Mermaid on the same Confluence page?

Yes. Both macros are independent and can coexist on the same page without conflict. A common pattern is to use Mermaid for sequence diagrams and flowcharts, and Graphviz for dependency graphs and data models, all on the same architecture documentation page.

Does Graphviz Charts for Confluence support export?

The rendered diagram can be exported using Confluence's built-in export features. When you export the page to PDF, the Graphviz diagram is included as part of the page content. You can also use browser print-to-PDF or screenshot tools to capture the rendered diagram independently.

How large can Graphviz diagrams get before performance suffers?

Graphviz's native C engine is highly optimized and can handle graphs with hundreds of nodes efficiently. For most practical use cases in Confluence documentation, diagrams stay under 200 nodes and render in under a second. Very large graphs (500+ nodes) may take longer to render and could benefit from the sfdp layout engine, which is designed for scalability. For readability purposes, consider splitting very large graphs into multiple focused diagrams linked together.

Can I use variables, loops, or conditional logic in DOT?

DOT itself is a static description language and does not support variables or logic. However, because DOT is plain text, you can generate it programmatically using scripts, templates, or Confluence's template variables. Teams often write Python or shell scripts that query their codebase or infrastructure and output DOT code, which they then paste into the Graphviz macro.

Is the DOT code visible to page viewers?

No. Page viewers see only the rendered diagram. The DOT source code is stored inside the macro and is only visible when editing the page. This keeps your documentation pages clean while preserving the text-based source for editors who need to update the diagram.

Related resources

• Graphviz Charts for Confluence -- full usage guide -- installation, configuration, and all layout engine options
• How to create flowcharts in Confluence -- flowchart tutorial comparing Mermaid, Excalidraw, and Graphviz
• Mermaid troubleshooting FAQ -- fixes for common Mermaid rendering issues in Confluence
• How to create architecture diagrams in Confluence -- step-by-step architecture diagram guide with copy-paste examples
• Confluence diagram tools compared -- side-by-side comparison of all NGPILOT diagramming apps

Graphviz Charts for Confluence gives your team a powerful way to create complex, auto-laid-out diagrams directly inside Confluence. The DOT language is straightforward to learn, the layout engine handles positioning automatically, and the text-based approach keeps your diagrams version-controlled and easy to maintain. Whether you are documenting microservices dependencies, database schemas, or network topologies, Graphviz produces clean, consistent diagrams that scale with your documentation.