json-canvas
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.
obsidianmd · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add obsidianmd/obsidian-skills --skill json-canvas技能说明
name: json-canvas description: 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.
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 objectsedges(optional): Array of edge objects connecting nodes
Common Workflows
1. Create a New Canvas
- Create a
.canvasfile with the base structure{"nodes": [], "edges": []} - Generate unique 16-character hex IDs for each node (e.g.,
"6f0ad84f44ce9c17") - Add nodes with required fields:
id,type,x,y,width,height - Add edges referencing valid node IDs via
fromNodeandtoNode - Validate: Parse the JSON to confirm it is valid. Verify all
fromNode/toNodevalues exist in the nodes array
2. Add a Node to an Existing Canvas
- Read and parse the existing
.canvasfile - Generate a unique ID that does not collide with existing node or edge IDs
- Choose position (
x,y) that avoids overlapping existing nodes (leave 50-100px spacing) - Append the new node object to the
nodesarray - Optionally add edges connecting the new node to existing nodes
- Validate: Confirm all IDs are unique and all edge references resolve to existing nodes
3. Connect Two Nodes
- Identify the source and target node IDs
- Generate a unique edge ID
- Set
fromNodeandtoNodeto the source and target IDs - Optionally set
fromSide/toSide(top, right, bottom, left) for anchor points - Optionally set
labelfor descriptive text on the edge - Append the edge to the
edgesarray - Validate: Confirm both
fromNodeandtoNodereference existing node IDs
4. Edit an Existing Canvas
- Read and parse the
.canvasfile as JSON - Locate the target node or edge by
id - Modify the desired attributes (text, position, color, etc.)
- Write the updated JSON back to the file
- 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 |