Diagrams Overview

ArchDoc supports creating diagrams directly in your documents, making technical documentation more visual and easier to understand.

Supported Diagram Types

Choosing the Right Tool

Excalidraw

Excalidraw provides a whiteboard-like experience:

• Hand-drawn aesthetic: Casual, approachable style
• Freeform drawing: Complete creative control
• Rich elements: Shapes, arrows, text, images
• Interactive: Edit directly in the document

Best for:

• Architecture diagrams
• System overviews
• Concept illustrations
• Collaborative sketching

Learn more about Excalidraw →

Mermaid

Mermaid creates diagrams from text:

• Text-based: Write diagrams as code
• Automatic layout: No manual positioning
• Version-friendly: Easy to track changes
• Multiple types: Flowcharts, sequences, and more

Best for:

• Flowcharts
• Sequence diagrams
• State machines
• Entity relationships

Learn more about Mermaid →

Draw.io

Draw.io embeds the full diagrams.net editor:

• Rich shape libraries: AWS, GCP, Azure, Kubernetes, UML, BPMN, networking, mockups
• Polished output: SVG-based, scales without quality loss
• Strict notation: First-class support for UML, BPMN, and ER diagrams
• Embedded editor: Open the full editor in a fullscreen overlay from inside the document

Best for:

• Detailed architecture diagrams
• UML / BPMN
• Network and infrastructure topology
• Mockups and wireframes

Learn more about Draw.io →

Examples

Architecture with Excalidraw

Create visual system architectures:

┌─────────────┐     ┌─────────────┐
│   Client    │────▶│  API Server │
└─────────────┘     └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  Database   │
                    └─────────────┘

Flow with Mermaid

Create flowcharts with text:

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

When to Use Diagrams

Do Use Diagrams For

✅ Complex systems - Show component relationships ✅ Processes - Illustrate step-by-step flows ✅ Decisions - Visualize decision trees ✅ Data flows - Show how data moves ✅ States - Illustrate state machines

Consider Alternatives For

⚠️ Simple lists - Bullet points may be clearer ⚠️ Comparisons - Tables might work better ⚠️ Linear processes - Numbered lists could suffice

Best Practices

Keep Diagrams Focused

• One concept per diagram
• Don't overcrowd with details
• Use multiple diagrams for complex systems

Add Context

• Explain the diagram in text
• Label important elements
• Reference diagrams in your writing

Maintain Consistency

• Use similar styles across documents
• Keep color schemes consistent
• Follow team conventions

Consider Updates

• Will the diagram need frequent updates?
• Mermaid is easier to update (text-based)
• Excalidraw offers more visual control

Getting Started

1. Excalidraw: Click the diagram button (✏️) in the toolbar
2. Mermaid: Create a code block with language mermaid in preview mode
3. Draw.io: Click the Draw.io button in the toolbar to insert a block, then click Edit on the block to open the fullscreen editor

Choose based on your needs and start creating visual documentation!