Skip to main content

​
canvas

Create an Obsidian canvas file to visualize concepts and connections. 
async def canvas(
    nodes: List[Dict[str, Any]],
    edges: List[Dict[str, Any]],
    title: str,
    directory: str,
    project: Optional[str] = None,
    workspace: Optional[str] = None,
    context: Context | None = None,
) -> str

​
Parameters

​
nodes
list[dict]
required
List of node objects following JSON Canvas 1.0 spec. Each node must have:
  • id (string) - Unique identifier
  • type (string) - Node type: “file”, “text”, “link”, or “group”
  • x (number) - X coordinate in pixels
  • y (number) - Y coordinate in pixels
  • width (number) - Width in pixels
  • height (number) - Height in pixels
Additional properties by type:
  • file nodes: file (string) - Path to file (e.g., “docs/Document.md”)
  • text nodes: text (string) - Text content
  • link nodes: url (string) - URL to link to
  • group nodes: Group styling properties
Optional properties:
  • color (string) - Color code “1”-“6” or hex value
  • label (string) - Node label
​
edges
list[dict]
required
List of edge objects following JSON Canvas 1.0 spec. Each edge must have:
  • id (string) - Unique identifier
  • fromNode (string) - Source node ID
  • toNode (string) - Target node ID
Optional properties:
  • label (string) - Edge label
  • color (string) - Color code or hex value
  • fromSide (string) - “top”, “right”, “bottom”, “left”
  • toSide (string) - “top”, “right”, “bottom”, “left”
​
title
string
required
The title of the canvas (saved as title.canvas)
​
directory
string
required
Directory path relative to project root. Examples:
  • diagrams
  • projects/2025
  • visual/maps
​
project
string
Project name to create canvas in. Optional - server resolves using hierarchy.
​
workspace
string
Cloud workspace name or tenant_id

​
Returns

​
result
string
A summary of the created canvas file including:
  • Creation/update status
  • File path
  • Confirmation that canvas is ready to open in Obsidian

​
JSON Canvas Structure

The canvas file follows the JSON Canvas 1.0 specification: 
{
  "nodes": [
    {
      "id": "node1",
      "type": "file",
      "file": "docs/Document.md",
      "x": 0,
      "y": 0,
      "width": 400,
      "height": 300,
      "color": "1"
    },
    {
      "id": "node2",
      "type": "text",
      "text": "## Important Note\n\nThis is a text node.",
      "x": 500,
      "y": 0,
      "width": 400,
      "height": 200
    },
    {
      "id": "node3",
      "type": "link",
      "url": "https://example.com",
      "x": 1000,
      "y": 0,
      "width": 300,
      "height": 150
    }
  ],
  "edges": [
    {
      "id": "edge1",
      "fromNode": "node1",
      "toNode": "node2",
      "label": "connects to",
      "color": "2"
    },
    {
      "id": "edge2",
      "fromNode": "node2",
      "toNode": "node3",
      "fromSide": "right",
      "toSide": "left"
    }
  ]
}

​
Node Types

​
File Node

References an existing file in the knowledge base: 
{
  "id": "file-node",
  "type": "file",
  "file": "docs/Document Name.md",
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 300
}
Important: Use the exact file path as shown in Obsidian, not permalink format.

​
Text Node

Contains markdown text content: 
{
  "id": "text-node",
  "type": "text",
  "text": "## Heading\n\nMarkdown content here.",
  "x": 500,
  "y": 0,
  "width": 400,
  "height": 250
}
Contains a URL: 
{
  "id": "link-node",
  "type": "link",
  "url": "https://example.com",
  "x": 1000,
  "y": 0,
  "width": 300,
  "height": 150
}

​
Group Node

Groups other nodes visually: 
{
  "id": "group-node",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 600,
  "height": 500,
  "label": "Related Concepts",
  "color": "3"
}

​
Edge Configuration

​
Basic Edge

{
  "id": "edge1",
  "fromNode": "node1",
  "toNode": "node2"
}

​
Labeled Edge

{
  "id": "edge2",
  "fromNode": "node1",
  "toNode": "node2",
  "label": "depends on",
  "color": "1"
}

​
Directional Edge

{
  "id": "edge3",
  "fromNode": "node1",
  "toNode": "node2",
  "fromSide": "right",
  "toSide": "left"
}
Valid sides: "top", "right", "bottom", "left"

​
Color Codes

Colors can be specified as:
  • Numbered colors: “1” through “6” (Obsidian’s default palette)
  • Hex colors: “#FF5733”, “#3498DB”, etc.

​
Examples

​
Simple Concept Map

canvas(
    nodes=[
        {
            "id": "concept1",
            "type": "text",
            "text": "# Main Concept",
            "x": 0,
            "y": 0,
            "width": 400,
            "height": 200
        },
        {
            "id": "concept2",
            "type": "text",
            "text": "# Related Concept",
            "x": 500,
            "y": 0,
            "width": 400,
            "height": 200
        }
    ],
    edges=[
        {
            "id": "edge1",
            "fromNode": "concept1",
            "toNode": "concept2",
            "label": "relates to"
        }
    ],
    title="Concept Map",
    directory="diagrams"
)

​
Document Relationship Diagram

canvas(
    nodes=[
        {
            "id": "spec",
            "type": "file",
            "file": "specs/API Specification.md",
            "x": 0,
            "y": 0,
            "width": 400,
            "height": 300,
            "color": "1"
        },
        {
            "id": "impl",
            "type": "file",
            "file": "docs/Implementation.md",
            "x": 500,
            "y": 0,
            "width": 400,
            "height": 300,
            "color": "2"
        },
        {
            "id": "tests",
            "type": "file",
            "file": "docs/Test Plan.md",
            "x": 1000,
            "y": 0,
            "width": 400,
            "height": 300,
            "color": "3"
        }
    ],
    edges=[
        {
            "id": "e1",
            "fromNode": "spec",
            "toNode": "impl",
            "label": "implements"
        },
        {
            "id": "e2",
            "fromNode": "impl",
            "toNode": "tests",
            "label": "tested by"
        }
    ],
    title="API Development Flow",
    directory="visual/maps",
    project="work-project"
)

​
Process Flow with Groups

canvas(
    nodes=[
        {
            "id": "group1",
            "type": "group",
            "x": -50,
            "y": -50,
            "width": 600,
            "height": 400,
            "label": "Planning Phase",
            "color": "4"
        },
        {
            "id": "step1",
            "type": "text",
            "text": "## Requirements",
            "x": 0,
            "y": 0,
            "width": 250,
            "height": 150
        },
        {
            "id": "step2",
            "type": "text",
            "text": "## Design",
            "x": 300,
            "y": 0,
            "width": 250,
            "height": 150
        },
        {
            "id": "step3",
            "type": "text",
            "text": "## Implementation",
            "x": 600,
            "y": 0,
            "width": 250,
            "height": 150
        }
    ],
    edges=[
        {
            "id": "e1",
            "fromNode": "step1",
            "toNode": "step2",
            "fromSide": "right",
            "toSide": "left"
        },
        {
            "id": "e2",
            "fromNode": "step2",
            "toNode": "step3",
            "fromSide": "right",
            "toSide": "left"
        }
    ],
    title="Development Process",
    directory="diagrams"
)

​
Important Notes

  1. File Paths: When referencing files, use the exact path as shown in Obsidian (e.g., “docs/Document Name.md”), not permalink format.
  2. File Existence: For file nodes, the referenced file must exist in the knowledge base.
  3. Coordinates: Position nodes using x,y coordinates in pixels. Plan a logical layout before creating the canvas.
  4. Node Sizing: Provide appropriate width and height for each node based on its content.
  5. Uniqueness: Each node and edge must have a unique id.
  6. Updates: If a canvas file already exists, it will be updated with the new content.

​
See Also

For the full JSON Canvas 1.0 specification, see the canvas spec resource.

Build docs developers (and LLMs) love

Get started for freeTalk to us