The Complete Guide to Mastering Ezdiag Assuming you are a software developer or data engineer using Ezdiag—the popular open-source Markdown-to-diagram tool—to generate architecture and sequence diagrams directly from your code repository, this guide is tailored for you.
Ezdiag allows you to build complex, professional diagrams using simple, human-readable text. By moving away from drag-and-drop interfaces, you can version-control your diagrams alongside your source code. 🛠️ Core Syntax Essentials
Every Ezdiag file relies on a clean, declarative structure. Master these three foundational blocks to build any diagram. 1. Node Declaration
Nodes represent your system components. Define them with unique IDs and clean display labels.
block { web_server [label = “Nginx Web Server”]; app_api [label = “FastAPI application”]; db_cluster [label = “PostgreSQL DB Cluster”]; } Use code with caution. 2. Grouping and Nesting
Keep your architecture organized. Use brackets to group related services into networks, clouds, or security zones.
group cloud_provider { label = “AWS Cloud Instance”; color = “#f2f2f2”; web_server; app_api; } Use code with caution. 3. Edge Connections
Connect your nodes using directional arrows. You can inject descriptive text directly onto the connector lines.
web_server -> app_api [label = “Reverse Proxies HTTPS”]; app_api -> db_cluster [label = “Read/Write Port 5432”]; Use code with caution. 🚀 Advanced Layout Techniques
Standard layouts can get messy as your infrastructure scales. Use these parameters to force clean positioning.
Orientation Control: Switch your diagram flow from vertical to horizontal layout.
orientation = portrait; // Top-to-bottom flow orientation = landscape; // Left-to-right flow Use code with caution.
Edge Weighting: Force critical paths to stay straight and close together.
node_a -> node_b [weight = 3]; // Higher weight pulls nodes closer Use code with caution.
Explicit Spacing: Adjust the global canvas density to prevent crowded text.
node_width = 160; // Standardizes node block size span_width = 120; // Extends horizontal spacing between columns Use code with caution. 🎨 Professional Styling Standards
Default diagrams look generic. Apply a consistent color palette and explicit typography rules to make your diagrams production-ready. The Modern Tech Palette
Avoid bright, saturated default colors. Use muted hex codes for a modern tech stack aesthetic: Primary Elements: #2C3E50 (Deep Slate Blue) Secondary/Workers: #18BC9C (Teal Accent) Background Fills: #ECF0F1 (Light Grey Grouping) Custom Attribute Injection
Apply global styles at the top of your document to keep individual node declarations clean.
diagram { default_node_color = “#2C3E50”; default_text_color = “#FFFFFF”; default_shape = “roundedbox”; } Use code with caution. 🤖 CI/CD Automation Pipeline
The true power of Ezdiag is automation. Never manually export a PNG or SVG again. Integrate this compilation step directly into your GitHub Actions workflow to auto-generate updated diagrams on every code push.
name: Generate Architecture Diagrams on: [push] jobs: render_diagrams: runs-on: ubuntu-latest steps: - name: Checkout Code uses: actions/checkout@v4 - name: Install Ezdiag Toolchain run: pip install ezdiag - name: Compile Text to SVG run: ezdiag -Tsvg architecture.diag -o ./docs/images/architecture.svg Use code with caution. Proposing Next Steps
To help me refine this guide for your specific needs, please share a few more details:
What specific type of diagram are you trying to build (e.g., microservices architecture, sequential API calls, cloud infrastructure)?
Leave a Reply