Index of every page on this site: llms.txt
All skills
obsidianmd avatar

/json-canvas

@b110b2f
by Obsidianobsidianmd/obsidian-skills53k stars
3,795
Run it yourself

Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases, mind maps, flowcharts, or when the user mentions Canvas files in Obsidian.

Use this Skill: https://skilld.dev/gh/obsidianmd/obsidian-skills/json-canvas

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈60 tokens for metadata: the name and description. ≈2.1k when used: this file. ≈1.6k more on demand in 1 file.

Description uses 3.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈239 characters, or 3.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

JSON Canvas Skill

File Structure

A canvas file (.canvas) contains two top-level arrays following the JSON Canvas Spec 1.0:

{
  "nodes": [],
  "edges": []
}
  • nodes (optional): Array of node objects
  • edges (optional): Array of edge objects connecting nodes

Common Workflows

1. Create a New Canvas

  1. Create a .canvas file with the base structure {"nodes": [], "edges": []}
  2. Generate unique 16-character hex IDs for each node (e.g., "6f0ad84f44ce9c17")
  3. Add nodes with required fields: id, type, x, y, width, height
  4. Add edges referencing valid node IDs via fromNode and toNode
  5. Validate: Parse the JSON to confirm it is valid. Verify all fromNode/toNode values exist in the nodes array

2. Add a Node to an Existing Canvas

  1. Read and parse the existing .canvas file
  2. Generate a unique ID that does not collide with existing node or edge IDs
  3. Choose position (x, y) that avoids overlapping existing nodes (leave 50-100px spacing)
  4. Append the new node object to the nodes array
  5. Optionally add edges connecting the new node to existing nodes
  6. Validate: Confirm all IDs are unique and all edge references resolve to existing nodes

3. Connect Two Nodes

  1. Identify the source and target node IDs
  2. Generate a unique edge ID
  3. Set fromNode and toNode to the source and target IDs
  4. Optionally set fromSide/toSide (top, right, bottom, left) for anchor points
  5. Optionally set label for descriptive text on the edge
  6. Append the edge to the edges array
  7. Validate: Confirm both fromNode and toNode reference existing node IDs

4. Edit an Existing Canvas

  1. Read and parse the .canvas file as JSON
  2. Locate the target node or edge by id
  3. Modify the desired attributes (text, position, color, etc.)
  4. Write the updated JSON back to the file
  5. Validate: Re-check all ID uniqueness and edge reference integrity after editing

Nodes

Nodes are objects placed on the canvas. Array order determines z-index: first node = bottom layer, last node = top layer.

Generic Node Attributes

Attribute Required Type Description
id Yes string Unique 16-char hex identifier
type Yes string text, file, link, or group
x Yes integer X position in pixels
y Yes integer Y position in pixels
width Yes integer Width in pixels
height Yes integer Height in pixels
color No canvasColor Preset "1"-"6" or hex (e.g., "#FF0000")

Text Nodes

Attribute Required Type Description
text Yes string Plain text with Markdown syntax
{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 200,
  "text": "# Hello World\n\nThis is **Markdown** content."
}

Newline pitfall: Use \n for line breaks in JSON strings. Do not use the literal \\n -- Obsidian renders that as the characters \ and n.

Quote escaping pitfall: Double quotes inside text content must be escaped as \". For example, the text 公司的"外交官" must be stored as "text": "公司的\"外交官\"". Unescaped quotes break the JSON parse and the canvas will fail to render. When generating canvas JSON programmatically, always use a JSON serializer rather than manual string concatenation.

Write .canvas files directly. Don't create them with obsidian create content=, which turns every \n into a raw newline and breaks the JSON.

File Nodes

Attribute Required Type Description
file Yes string Path to file within the system
subpath No string Link to heading or block (starts with #)

File path escaping: If a file name contains double quotes, they must be escaped as \" in the JSON string. For example, a file named My "Notes".md should be referenced as "file": "My \"Notes\".md".

{
  "id": "a1b2c3d4e5f67890",
  "type": "file",
  "x": 500,
  "y": 0,
  "width": 400,
  "height": 300,
  "file": "Attachments/diagram.png"
}

Link Nodes

Attribute Required Type Description
url Yes string External URL
{
  "id": "c3d4e5f678901234",
  "type": "link",
  "x": 1000,
  "y": 0,
  "width": 400,
  "height": 200,
  "url": "https://obsidian.md"
}

Group Nodes

Groups are visual containers for organizing other nodes. Position child nodes inside the group's bounds.

Attribute Required Type Description
label No string Text label for the group
background No string Path to background image
backgroundStyle No string cover, ratio, or repeat
{
  "id": "d4e5f6789012345a",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 1000,
  "height": 600,
  "label": "Project Overview",
  "color": "4"
}

Edges

Edges connect nodes via fromNode and toNode IDs.

Attribute Required Type Default Description
id Yes string - Unique identifier
fromNode Yes string - Source node ID
fromSide No string - top, right, bottom, or left
fromEnd No string none none or arrow
toNode Yes string - Target node ID
toSide No string - top, right, bottom, or left
toEnd No string arrow none or arrow
color No canvasColor - Line color
label No string - Text label
{
  "id": "0123456789abcdef",
  "fromNode": "6f0ad84f44ce9c17",
  "fromSide": "right",
  "toNode": "a1b2c3d4e5f67890",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "leads to"
}

Colors

The canvasColor type accepts either a hex string or a preset number:

Preset Color
"1" Red
"2" Orange
"3" Yellow
"4" Green
"5" Cyan
"6" Purple

Preset color values are intentionally undefined -- applications use their own brand colors.

ID Generation

Generate 16-character lowercase hexadecimal strings (64-bit random value):

"6f0ad84f44ce9c17"
"a3b2c1d0e9f8a7b6"

Layout Guidelines

  • Coordinates can be negative (canvas extends infinitely)
  • x increases right, y increases down; position is the top-left corner
  • Space nodes 50-100px apart; leave 20-50px padding inside groups
  • Align to grid (multiples of 10 or 20) for cleaner layouts
Node Type Suggested Width Suggested Height CJK Width (1.5x)
Small text 200-300 80-150 300-450
Medium text 300-450 150-300 450-675
Large text 400-600 300-500 600-900
File preview 300-500 200-400 450-750
Link preview 250-400 100-200 375-600

CJK text sizing: CJK characters (Chinese, Japanese, Korean) are wider than Latin characters. For content primarily in CJK languages, multiply the suggested width by ~1.5× to avoid cramped layouts and awkward line breaks.

Validation Checklist

After creating or editing a canvas file, verify:

  1. All id values are unique across both nodes and edges
  2. Every fromNode and toNode references an existing node ID
  3. Required fields are present for each node type (text for text nodes, file for file nodes, url for link nodes)
  4. type is one of: text, file, link, group
  5. fromSide/toSide values are one of: top, right, bottom, left
  6. fromEnd/toEnd values are one of: none, arrow
  7. Color presets are "1" through "6" or valid hex (e.g., "#FF0000")
  8. Double quotes in text and file values are properly escaped as \"
  9. JSON is valid and parseable

If validation fails, check for duplicate IDs, dangling edge references, or malformed JSON strings (especially unescaped newlines in text content).

Complete Examples

See references/EXAMPLES.md for full canvas examples including mind maps, project boards, research canvases, and flowcharts.

References

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    The skill provides instructions for the agent to manage Obsidian JSON Canvas files. This involves a potential surface for indirect prompt injection, as the agent reads and writes data that may contain untrusted instructions in text fields, although no explicit malicious code was found.

  • Socket7d

    No alerts

  • Snyk7d

    Risk: LOW · No issues

Signed by skilld at b110b2f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 12 hours ago.

Activeupdated 2 weeks ago
  • json-canvas
  • obsidian
  • visualization
  • flowchart
  • mindmap
  • graph
  • canvas
  • json

README badge

README badge for obsidianmd/obsidian-skills/json-canvas

Reads and writes JSON Canvas (.canvas) files in Obsidian, creating and editing nodes (text, file, link, group), edges, and connections according to the JSON Canvas 1.0 spec. Use this skill when manipulating canvas files programmatically—mind maps, flowcharts, project boards, or any visual diagram that Obsidian renders as .canvas.

Generated from the current SKILL.md.

What file format does this skill work with?
This skill creates and edits `.canvas` files, which are JSON files following the JSON Canvas Spec 1.0 used by Obsidian for visual canvases, mind maps, and flowcharts.
What types of nodes can I create?
You can create text nodes (with Markdown support), file nodes (linking to files or headings), link nodes (external URLs), and group nodes (visual containers for organizing other nodes).
How do I connect nodes together?
Create edges by specifying a unique ID, source node ID (`fromNode`), target node ID (`toNode`), and optionally anchor sides (`fromSide`/`toSide`), arrow endpoints, and labels.
What validation does this skill perform?
The skill validates that all node and edge IDs are unique, all edge references point to existing nodes, required fields are present for each node type, and the JSON is parseable.
Does this skill support Markdown in text nodes?
Yes. Text nodes accept Markdown syntax, but newlines must be written as `\n` in the JSON string, not literal line breaks.

Generated from the current SKILL.md. These answers refresh after source changes.