Mastering JSON Canvas Layout Algorithms: Excalidraw Integration and Mermaid Diagram Generation

Published on ClawList.io | Category: Development | Author: Inspired by @AxtonLiu

---

If you've ever tried to programmatically generate visual diagrams and canvases, you know the pain: elements overlap, spacing feels arbitrary, and the result looks nothing like what a human designer would produce. That's exactly the problem that JSON Canvas layout algorithms solve — and in a recent viral tutorial by developer @AxtonLiu, the entire workflow from canvas generation to Mermaid-powered Markdown documentation is broken down in just five minutes.

In this post, we'll dive deep into what makes this approach powerful, how you can replicate it in your own projects, and why combining JSON Canvas, Excalidraw, and Mermaid diagrams is becoming a go-to stack for AI engineers and automation developers.

---

What Is JSON Canvas — and Why Does the Official Layout Fall Short?

JSON Canvas is an open specification for storing infinite canvas data in a portable, readable JSON format. Originally popularized by tools like Obsidian, it defines nodes, edges, colors, and positions in a straightforward schema:

{
  "nodes": [
    {
      "id": "node-1",
      "type": "text",
      "text": "Start Here",
      "x": 0,
      "y": 0,
      "width": 200,
      "height": 60
    },
    {
      "id": "node-2",
      "type": "text",
      "text": "Next Step",
      "x": 300,
      "y": 0,
      "width": 200,
      "height": 60
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "fromNode": "node-1",
      "toNode": "node-2"
    }
  ]
}

The problem? The official JSON Canvas spec doesn't prescribe a layout algorithm. When you're generating canvases programmatically — especially with AI agents producing dynamic content — you need a reliable way to position nodes so they don't collide, maintain readable spacing, and visually communicate relationships.

@AxtonLiu's custom layout algorithm addresses exactly this gap. Rather than dumping nodes at static coordinates or relying on manual placement, the algorithm:

• Calculates hierarchical levels based on node connectivity
• Distributes nodes horizontally with consistent padding
• Avoids edge crossings where possible using graph traversal logic
• Scales dynamically based on node content size

This is the difference between a canvas that looks machine-generated and one that a developer would actually want to share with their team.

---

Generating Excalidraw Hand-Drawn Source Files from JSON Canvas

One of the most impressive aspects of this workflow is the bridge between JSON Canvas data and Excalidraw's hand-drawn aesthetic. Excalidraw has become enormously popular for technical diagrams precisely because its sketchy, whiteboard-style rendering makes complex systems feel approachable.

The workflow works like this:

1. Define your data model in JSON Canvas format (nodes + edges)
2. Run the layout algorithm to compute x, y, width, and height values
3. Transform the JSON Canvas output into Excalidraw's .excalidraw file format
4. Open in Excalidraw to get an immediately shareable, editable hand-drawn diagram

Here's a simplified example of what the Excalidraw element structure looks like after conversion:

{
  "type": "excalidraw",
  "version": 2,
  "elements": [
    {
      "type": "rectangle",
      "id": "node-1",
      "x": 100,
      "y": 150,
      "width": 200,
      "height": 60,
      "roughness": 1,
      "strokeColor": "#1e1e1e",
      "backgroundColor": "#a5d8ff",
      "text": "Start Here"
    },
    {
      "type": "arrow",
      "id": "edge-1",
      "startBinding": { "elementId": "node-1" },
      "endBinding": { "elementId": "node-2" },
      "roughness": 1
    }
  ]
}

The key property here is "roughness": 1 — this tells Excalidraw to render elements in its signature hand-drawn style. Setting it to 0 gives you clean, polished lines instead.

Pro tip from the tutorial: When installing the tool, don't forget the references directory. This is a common gotcha — the references folder contains the schema mappings and style presets that drive the Excalidraw conversion. Missing it will result in unstyled or broken output files.

---

Generating Markdown Documents with Embedded Mermaid Diagrams

The second major capability in this workflow is auto-generating Markdown documentation that includes Mermaid diagram syntax. This is a game-changer for AI-powered documentation pipelines.

Mermaid is a JavaScript-based diagramming tool that renders diagrams directly from plain text inside Markdown code blocks. It's natively supported by GitHub, GitLab, Notion, Obsidian, and dozens of other platforms — which makes it the ideal format for programmatically generated technical docs.

Here's an example of what the generated Markdown output looks like:

# System Architecture Overview

This document was auto-generated from the project canvas.

## Data Flow

```mermaid
graph TD
    A[User Input] --> B[API Gateway]
    B --> C{Router}
    C -->|Route A| D[Service Alpha]
    C -->|Route B| E[Service Beta]
    D --> F[Database]
    E --> F[Database]
    F --> G[Response]
```

## Key Components

- **API Gateway**: Handles authentication and rate limiting
- **Router**: Distributes traffic based on request type
- **Service Alpha / Beta**: Business logic microservices

What makes this particularly powerful for AI automation developers is the pipeline potential:

1. An AI agent maps out a system or workflow as a graph
2. The JSON Canvas layout algorithm positions everything cleanly
3. The Mermaid exporter converts the graph into documentation-ready syntax
4. The resulting Markdown is committed to a repo, shared with stakeholders, or fed into another AI step

This creates a fully automated diagram-to-documentation pipeline with zero manual layout work.

Use Cases Where This Workflow Shines

• AI agent workflow visualization: Map out multi-step LLM pipelines and export them as readable diagrams automatically
• System architecture documentation: Generate living docs that update whenever your canvas changes
• Code review aids: Produce Mermaid flowcharts from pull request logic automatically
• Technical onboarding materials: Convert complex system graphs into hand-drawn Excalidraw files that feel less intimidating for new team members
• OpenClaw skill development: Visualize and document AI skill dependency trees within the ClawList.io ecosystem

---

Getting Started: Installation Tips

Based on @AxtonLiu's tutorial, here's the quick-start checklist:

# Clone the repository
git clone https://github.com/axtonliu/json-canvas-layout

# Install dependencies
npm install

# ⚠️ Critical: ensure the references directory is present
ls ./references   # Should show schema files and style presets

# Run the layout algorithm on a sample canvas
node index.js --input sample.canvas --output output.excalidraw

# Generate Markdown with Mermaid
node index.js --input sample.canvas --format markdown --output docs/architecture.md

Remember: The references directory is not always included in default npm installs if the package is distributed that way — double-check it's present before running the tool. This is the most common setup issue reported by early users.

---

Conclusion: Why This Stack Matters for AI Developers

The combination of JSON Canvas + custom layout algorithms + Excalidraw + Mermaid represents a mature, production-ready approach to programmatic diagram generation. As AI agents become increasingly responsible for designing, documenting, and communicating complex systems, the ability to auto-generate beautiful, readable visual artifacts becomes a core capability — not a nice-to-have.

What @AxtonLiu has built is more than a utility script — it's a blueprint for how AI-native documentation should work: structured data in, human-readable diagrams out, with no manual intervention required.

Whether you're building OpenClaw skills on ClawList.io, developing multi-agent pipelines, or simply trying to keep your architecture documentation in sync with reality, this workflow deserves a place in your developer toolkit.

Watch the full 5-minute tutorial video on YouTube (linked in @AxtonLiu's original post) and check out the source code to get started today.

---

Found this useful? Share it with your team and follow @AxtonLiu for more developer tools and AI automation insights. Explore more resources like this at ClawList.io.

---

Tags: json-canvas excalidraw mermaid diagram-generation ai-automation developer-tools markdown layout-algorithms openclaw documentation