Advanced JSON Canvas

A specialized skill for creating and editing JSON Canvas files used in Obsidian and other applications. Covers the JSON Canvas specification, node types, edge connections, layout algorithms, and integration with knowledge management workflows.

When to Use This Skill

Choose this skill when:

• Creating JSON Canvas files (.canvas) for visual note-taking and knowledge mapping
• Building canvas-based workflows in Obsidian
• Generating visual diagrams and mind maps in canvas format
• Connecting notes, links, and media in spatial layouts
• Automating canvas creation from structured data

Consider alternatives when:

• Creating Mermaid diagrams → use a Mermaid diagramming skill
• Working with draw.io/excalidraw → use those specific tools
• Building interactive web visualizations → use a D3/canvas skill
• Writing plain Markdown notes → use an Obsidian Markdown skill

Quick Start

Copy
{
  "nodes": [
    {
      "id": "node-1",
      "type": "text",
      "x": 0, "y": 0,
      "width": 250, "height": 100,
      "text": "# Main Idea\nThis is the central concept.",
      "color": "1"
    },
    {
      "id": "node-2",
      "type": "text",
      "x": 350, "y": -50,
      "width": 200, "height": 80,
      "text": "## Supporting Point A"
    },
    {
      "id": "node-3",
      "type": "file",
      "x": 350, "y": 100,
      "width": 200, "height": 80,
      "file": "notes/research.md"
    },
    {
      "id": "node-4",
      "type": "link",
      "x": 0, "y": 200,
      "width": 250, "height": 150,
      "url": "https://example.com/reference"
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "fromNode": "node-1",
      "fromSide": "right",
      "toNode": "node-2",
      "toSide": "left",
      "label": "supports"
    },
    {
      "id": "edge-2",
      "fromNode": "node-1",
      "fromSide": "right",
      "toNode": "node-3",
      "toSide": "left",
      "color": "3"
    }
  ]
}

Core Concepts

Node Types

Type	Purpose	Key Properties
text	Markdown text content	text: Markdown string
file	Reference to a vault file	file: Path to .md file
link	External URL embed	url: URL string
group	Visual grouping container	label: Group name

Edge Properties

Property	Type	Description
fromNode	string	Source node ID
toNode	string	Target node ID
fromSide	string	Source side: top, right, bottom, left
toSide	string	Target side: top, right, bottom, left
fromEnd	string	Arrow style: none or arrow
toEnd	string	Arrow style: none or arrow
color	string	Color preset: 1-6
label	string	Edge label text

Canvas Generation from Data

Copy
// Generate canvas from structured data
interface CanvasGenerator {
  generateFromOutline(outline: Outline): Canvas;
  generateFromGraph(nodes: GraphNode[], edges: GraphEdge[]): Canvas;
  autoLayout(canvas: Canvas, algorithm: 'tree' | 'force' | 'grid'): Canvas;
}

function generateFromOutline(outline: Outline): Canvas {
  const nodes: CanvasNode[] = [];
  const edges: CanvasEdge[] = [];
  let nodeIndex = 0;

  function processItem(item: OutlineItem, parentId: string | null, x: number, y: number) {
    const id = `node-${nodeIndex++}`;
    nodes.push({
      id, type: 'text',
      x, y, width: 250, height: 80,
      text: `## ${item.title}\n${item.description || ''}`,
    });
    if (parentId) {
      edges.push({
        id: `edge-${edges.length}`,
        fromNode: parentId, fromSide: 'right',
        toNode: id, toSide: 'left',
      });
    }
    item.children?.forEach((child, i) => {
      processItem(child, id, x + 350, y + i * 120);
    });
  }

  outline.items.forEach((item, i) => processItem(item, null, 0, i * 200));
  return { nodes, edges };
}

Configuration

Parameter	Type	Default	Description
defaultNodeWidth	number	250	Default node width in pixels
defaultNodeHeight	number	100	Default node height in pixels
layoutAlgorithm	string	'tree'	Auto-layout: tree, grid, or force-directed
nodeSpacing	number	100	Spacing between nodes in pixels
defaultEdgeStyle	string	'arrow'	Edge end style: arrow or none
colorPalette	string	'obsidian'	Color presets: obsidian default (1-6)

Best Practices

1. Use consistent node dimensions for visual harmony — Vary width (200-400px) based on content, but keep heights uniform within node groups. This creates clean alignment when nodes are positioned in rows or columns.

2. Connect edges to the nearest sides of nodes — Use fromSide and toSide that minimize edge crossings. Left-to-right flows should use fromSide: "right" and toSide: "left". Top-to-bottom flows use top and bottom.

3. Use groups to visually cluster related concepts — Group nodes create a background rectangle that visually groups related nodes. Size groups to contain their children with padding, and give them descriptive labels.

4. Generate unique IDs deterministically — Use slugified content or sequential counters for node IDs rather than random UUIDs. Deterministic IDs enable updating canvases without creating duplicates.

5. Validate against the JSON Canvas specification — The spec defines required and optional properties. Missing required properties or invalid types cause the canvas to fail to load. Validate before saving.

Common Issues

Nodes overlap after generation — Auto-layout algorithms may position nodes too close. Calculate minimum positions based on node dimensions plus spacing. Add collision detection to push overlapping nodes apart.

Canvas file doesn't load in Obsidian — Invalid JSON or missing required properties. Validate JSON syntax, ensure all nodes have id, type, x, y, width, and height. File-type nodes need valid file paths relative to the vault root.

Edge labels not visible — Edge labels are only visible when edges are long enough. Increase spacing between connected nodes or position labels at the midpoint. Very short edges can't display labels legibly.