D2 Diagramming Guide

D2 Diagramming Guide

D2 is a modern diagram scripting language that turns text into professional diagrams. This guide will help you create and embed beautiful diagrams in your TeamSite content using our AI-powered D2 integration.

Quick Start

Basic Syntax

Create diagrams using simple D2 shortcode syntax:

```text
# Direction of the diagram
direction: right

# Define shapes
start: Circle { label: "Start" }
process: Rectangle { label: "Process" }
end: Circle { label: "End" }

# Define connections
start -> process: "input"
process -> end: "output"

### Result

{{d2
direction: right

start: Circle { label: "Start" }
process: Rectangle { label: "Process" }
end: Circle { label: "End" }
start -> process: "input"
process -> end: "output"
}}

## Using the AI Agent

For complex diagrams or if you're unsure about D2 syntax, use our specialized AI agent:

Use the d2-diagram-generator agent to create a [diagram type] for [your concept]

### Examples of What to Ask:

- "Use the d2-diagram-generator agent to create an organizational chart for our sales team"
- "Use the d2-diagram-generator agent to create a flow diagram showing our customer onboarding process"
- "Use the d2-diagram-generator agent to create a system architecture diagram for our tech stack"

The agent will:
1. **Analyze your requirements** and ask clarifying questions
2. **Reference the latest D2 documentation** via Context7
3. **Generate optimal D2 code** based on best practices
4. **Provide integration instructions** for your content

## Supported Diagram Types

### 1. Flow Diagrams
Perfect for processes, workflows, and decision trees.

```markdown
```text
direction: down
start: Oval { label: "Start" }
check: Diamond { label: "Condition?" }
yes: Rectangle { label: "Yes Path" }
no: Rectangle { label: "No Path" }
end: Oval { label: "End" }

start -> check
check -> yes: "Yes"
check -> no: "No"
yes -> end
no -> end

{{d2
direction: down

start: Oval { label: "Start" }
check: Diamond { label: "Condition?" }
yes: Rectangle { label: "Yes Path" }
no: Rectangle { label: "No Path" }
end: Oval { label: "End" }
start -> check
check -> yes: "Yes"
check -> no: "No"
yes -> end
no -> end
}}

### 2. Organizational Charts
Ideal for team structures and hierarchies.

```markdown
{{d2
direction: down
ceo: Rectangle { label: "CEO" }
cto: Rectangle { label: "CTO" }
cfo: Rectangle { label: "CFO" }
cmo: Rectangle { label: "CMO" }

dev1: Rectangle { label: "Dev Team Lead" }
dev2: Rectangle { label: "Senior Developer" }

ceo -> cto
ceo -> cfo
ceo -> cmo
cto -> dev1
cto -> dev2
}}

direction: down
ceo: Rectangle { label: "CEO" }
cto: Rectangle { label: "CTO" }
cfo: Rectangle { label: "CFO" }
cmo: Rectangle { label: "CMO" }
dev1: Rectangle { label: "Dev Team Lead" }
dev2: Rectangle { label: "Senior Developer" }
ceo -> cto
ceo -> cfo
ceo -> cmo
cto -> dev1
cto -> dev2

3. System Architecture

Great for technical infrastructure and software design.

{{d2
direction: right
frontend: Rectangle {
  label: "Frontend"
  style.fill: "#e1f5fe"
}

backend: Rectangle {
  label: "Backend API"
  style.fill: "#e3f2fd"
}

database: Cylinder {
  label: "Database"
  style.fill: "#fce4ec"
}

cache: Rectangle {
  label: "Cache"
  style.fill: "#f3e5f5"
}

frontend -> backend: "REST API"
backend -> database: "SQL Queries"
backend -> cache: "Redis"
}}

direction: right
frontend: Rectangle {
  label: "Frontend"
  style.fill: "#e1f5fe"
}
backend: Rectangle {
  label: "Backend API"
  style.fill: "#e3f2fd"
}
database: Cylinder {
  label: "Database"
  style.fill: "#fce4ec"
}
cache: Rectangle {
  label: "Cache"
  style.fill: "#f3e5f5"
}
frontend -> backend: "REST API"
backend -> database: "SQL Queries"
backend -> cache: "Redis"

Advanced Features

Custom Styling

{{d2
# Custom colors and shapes
direction: down
important: Rectangle {
  label: "Critical Path"
  style.fill: "#ff5252"
  stroke: "#d32f2f"
  stroke-width: 2
}

normal: Rectangle {
  label: "Normal Path"
  style.fill: "#4caf50"
  stroke: "#388e3c"
  stroke-width: 1
}

important -> normal
}}

Theme Support

Diagrams automatically adapt to your site’s theme:

{{d2 theme="dark"
# This diagram will use dark theme colors
direction: right
user: Circle { label: "User" }
system: Rectangle { label: "System" }
user -> system: "interacts"
}}

Real-World Example: RVP Organizational Chart

Here’s a complex organizational chart showing a Regional Vice President (RVP) with 10 direct reports, each having 2 team members:

```text
direction: down
width="100%"

# RVP Level
rvp: Rectangle {
  label: "Regional Vice President"
  style.fill: "#1e88e5"
  font-color: white
}

# Regional Directors (10 direct reports)
rd1: Rectangle {
  label: "Regional Director 1"
  style.fill: "#43a047"
  font-color: white
}
rd2: Rectangle {
  label: "Regional Director 2"
  style.fill: "#43a047"
  font-color: white
}
rd3: Rectangle {
  label: "Regional Director 3"
  style.fill: "#43a047"
  font-color: white
}
rd4: Rectangle {
  label: "Regional Director 4"
  style.fill: "#43a047"
  font-color: white
}
rd5: Rectangle {
  label: "Regional Director 5"
  style.fill: "#43a047"
  font-color: white
}
rd6: Rectangle {
  label: "Regional Director 6"
  style.fill: "#43a047"
  font-color: white
}
rd7: Rectangle {
  label: "Regional Director 7"
  style.fill: "#43a047"
  font-color: white
}
rd8: Rectangle {
  label: "Regional Director 8"
  style.fill: "#43a047"
  font-color: white
}
rd9: Rectangle {
  label: "Regional Director 9"
  style.fill: "#43a047"
  font-color: white
}
rd10: Rectangle {
  label: "Regional Director 10"
  style.fill: "#43a047"
  font-color: white
}

# Team Members under RD1
rd1_tm1: Rectangle {
  label: "Team Member 1.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd1_tm2: Rectangle {
  label: "Team Member 1.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD2
rd2_tm1: Rectangle {
  label: "Team Member 2.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd2_tm2: Rectangle {
  label: "Team Member 2.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD3
rd3_tm1: Rectangle {
  label: "Team Member 3.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd3_tm2: Rectangle {
  label: "Team Member 3.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD4
rd4_tm1: Rectangle {
  label: "Team Member 4.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd4_tm2: Rectangle {
  label: "Team Member 4.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD5
rd5_tm1: Rectangle {
  label: "Team Member 5.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd5_tm2: Rectangle {
  label: "Team Member 5.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD6
rd6_tm1: Rectangle {
  label: "Team Member 6.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd6_tm2: Rectangle {
  label: "Team Member 6.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD7
rd7_tm1: Rectangle {
  label: "Team Member 7.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd7_tm2: Rectangle {
  label: "Team Member 7.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD8
rd8_tm1: Rectangle {
  label: "Team Member 8.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd8_tm2: Rectangle {
  label: "Team Member 8.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD9
rd9_tm1: Rectangle {
  label: "Team Member 9.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd9_tm2: Rectangle {
  label: "Team Member 9.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Team Members under RD10
rd10_tm1: Rectangle {
  label: "Team Member 10.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd10_tm2: Rectangle {
  label: "Team Member 10.2"
  style.fill: "#fb8c00"
  font-color: white
}

# Connections from RVP to Regional Directors
rvp -> rd1
rvp -> rd2
rvp -> rd3
rvp -> rd4
rvp -> rd5
rvp -> rd6
rvp -> rd7
rvp -> rd8
rvp -> rd9
rvp -> rd10

# Connections from Regional Directors to their team members
rd1 -> rd1_tm1
rd1 -> rd1_tm2

rd2 -> rd2_tm1
rd2 -> rd2_tm2

rd3 -> rd3_tm1
rd3 -> rd3_tm2

rd4 -> rd4_tm1
rd4 -> rd4_tm2

rd5 -> rd5_tm1
rd5 -> rd5_tm2

rd6 -> rd6_tm1
rd6 -> rd6_tm2

rd7 -> rd7_tm1
rd7 -> rd7_tm2

rd8 -> rd8_tm1
rd8 -> rd8_tm2

rd9 -> rd9_tm1
rd9 -> rd9_tm2

rd10 -> rd10_tm1
rd10 -> rd10_tm2

### Result: RVP Organizational Chart

{{d2
width="100%"
direction: down
rvp: Rectangle {
  label: "Regional Vice President"
  style.fill: "#1e88e5"
  font-color: white
}
rd1: Rectangle {
  label: "Regional Director 1"
  style.fill: "#43a047"
  font-color: white
}
rd2: Rectangle {
  label: "Regional Director 2"
  style.fill: "#43a047"
  font-color: white
}
rd3: Rectangle {
  label: "Regional Director 3"
  style.fill: "#43a047"
  font-color: white
}
rd4: Rectangle {
  label: "Regional Director 4"
  style.fill: "#43a047"
  font-color: white
}
rd5: Rectangle {
  label: "Regional Director 5"
  style.fill: "#43a047"
  font-color: white
}
rd6: Rectangle {
  label: "Regional Director 6"
  style.fill: "#43a047"
  font-color: white
}
rd7: Rectangle {
  label: "Regional Director 7"
  style.fill: "#43a047"
  font-color: white
}
rd8: Rectangle {
  label: "Regional Director 8"
  style.fill: "#43a047"
  font-color: white
}
rd9: Rectangle {
  label: "Regional Director 9"
  style.fill: "#43a047"
  font-color: white
}
rd10: Rectangle {
  label: "Regional Director 10"
  style.fill: "#43a047"
  font-color: white
}
rd1_tm1: Rectangle {
  label: "Team Member 1.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd1_tm2: Rectangle {
  label: "Team Member 1.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd2_tm1: Rectangle {
  label: "Team Member 2.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd2_tm2: Rectangle {
  label: "Team Member 2.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd3_tm1: Rectangle {
  label: "Team Member 3.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd3_tm2: Rectangle {
  label: "Team Member 3.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd4_tm1: Rectangle {
  label: "Team Member 4.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd4_tm2: Rectangle {
  label: "Team Member 4.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd5_tm1: Rectangle {
  label: "Team Member 5.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd5_tm2: Rectangle {
  label: "Team Member 5.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd6_tm1: Rectangle {
  label: "Team Member 6.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd6_tm2: Rectangle {
  label: "Team Member 6.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd7_tm1: Rectangle {
  label: "Team Member 7.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd7_tm2: Rectangle {
  label: "Team Member 7.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd8_tm1: Rectangle {
  label: "Team Member 8.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd8_tm2: Rectangle {
  label: "Team Member 8.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd9_tm1: Rectangle {
  label: "Team Member 9.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd9_tm2: Rectangle {
  label: "Team Member 9.2"
  style.fill: "#fb8c00"
  font-color: white
}
rd10_tm1: Rectangle {
  label: "Team Member 10.1"
  style.fill: "#fb8c00"
  font-color: white
}
rd10_tm2: Rectangle {
  label: "Team Member 10.2"
  style.fill: "#fb8c00"
  font-color: white
}
rvp -> rd1
rvp -> rd2
rvp -> rd3
rvp -> rd4
rvp -> rd5
rvp -> rd6
rvp -> rd7
rvp -> rd8
rvp -> rd9
rvp -> rd10
rd1 -> rd1_tm1
rd1 -> rd1_tm2
rd2 -> rd2_tm1
rd2 -> rd2_tm2
rd3 -> rd3_tm1
rd3 -> rd3_tm2
rd4 -> rd4_tm1
rd4 -> rd4_tm2
rd5 -> rd5_tm1
rd5 -> rd5_tm2
rd6 -> rd6_tm1
rd6 -> rd6_tm2
rd7 -> rd7_tm1
rd7 -> rd7_tm2
rd8 -> rd8_tm1
rd8 -> rd8_tm2
rd9 -> rd9_tm1
rd9 -> rd9_tm2
rd10 -> rd10_tm1
rd10 -> rd10_tm2
}}

## Shortcode Attributes

You can customize diagrams using these attributes:

```markdown
{{d2 theme="dark" width="100%" height="400px" class="my-diagram"
# D2 diagram code here
direction: right
start -> end
}}

Available Attributes

Attribute	Values	Default	Description
theme	light, dark, auto	auto	Diagram color theme
width	CSS width values	100%	Diagram container width
height	CSS height values	auto	Diagram container height
class	CSS class names	""	Additional CSS classes

Best Practices

Do's

• ✅ Use descriptive labels that clearly explain each element
• ✅ Keep diagrams focused on a single concept or process
• ✅ Use consistent styling across related diagrams
• ✅ Test on mobile devices to ensure responsiveness
• ✅ Leverage the AI agent for complex diagrams
• ✅ Add comments with # to explain complex sections

Don'ts

• ❌ Create overly complex diagrams that are hard to read
• ❌ Use too many colors that create visual noise
• ❌ Make diagrams too wide for mobile screens
• ❌ Include sensitive data in diagrams
• ❌ Use deprecated syntax - always ask the AI agent for current best practices

Troubleshooting

Common Issues

Diagram Not Rendering

• Check syntax for missing brackets or quotes
• Verify connections point to valid shapes
• Look for error messages in the diagram container

Layout Problems

• Adjust direction (up, down, left, right)
• Break large diagrams into smaller ones
• Use responsive sizing with percentage widths

Styling Issues

• Use hex colors with # prefix
• Apply styles consistently across similar elements
• Test theme compatibility in both light and dark modes

Getting Help

1. Use the D2 AI agent for syntax assistance
2. Check this guide for common patterns
3. Refer to Context7 documentation via the agent for latest features
4. Test in development before publishing to production

Performance Considerations

• Simple diagrams render instantly (<100ms)
• Complex diagrams may take 200-500ms to render
• Diagrams are cached for fast subsequent renders
• Large diagrams (50+ elements) may need optimization

Integration with Your Workflow

Content Creation Process

1. Plan your diagram - What story are you telling?
2. Use the AI agent - Get professional D2 code
3. Copy to your content - Use the shortcode format
4. Preview and adjust - Test on different screen sizes
5. Publish - Diagrams render automatically for your audience

Team Collaboration

• Share D2 code snippets with team members
• Use consistent styling across team documentation
• Leverage the agent to maintain quality standards
• Document best practices in your team wiki

---

This D2 diagramming system is powered by the latest D2.js library and integrates seamlessly with your TeamSite’s content management workflow. For additional support, reach out to your site administrators.