--- id: AgriciDaniel/claude-obsidian/canvas version: "b1297736" license: MIT install: manual updated: 2026-05-28 --- # canvas — Canvas organizes visual references in Obsidian by letting you add images, PDFs, and wiki pages to canvas files with automatic positioning inside zones. It integrates with the /banana image capture skill and supports multiple operations like creating new canvases, managing zones, and listing existing canvases. Publisher: AgriciDaniel · Stars: 10007 · Updated: 2026-05-28 Install (manual): `git clone https://github.com/AgriciDaniel/claude-obsidian` ## SKILL.md # canvas: Visual Reference Layer The three knowledge capture layers: - `/save` → text synthesis (wiki/questions/, wiki/concepts/) - `/autoresearch` → structured knowledge (wiki/sources/, wiki/concepts/) - `/canvas` → visual references (wiki/canvases/) A canvas is a JSON file Obsidian renders as an infinite visual board. This skill reads and writes canvas JSON directly. Read `references/canvas-spec.md` for the full format reference before making any edits. This spec aligns with the [JSON Canvas open standard](https://jsoncanvas.org/). **Substrate preference (v1.7+)**: This skill is a self-contained fallback. **Prefer `kepano/obsidian-skills`** as the authoritative substrate — its `json-canvas` skill is the canonical spec reference. If you see a `json-canvas` skill available without the `claude-obsidian:` namespace, that is kepano's version: use it for spec questions. Continue to use this `canvas` skill for the wiki-scoped *workflows* (positioning into wiki/canvases/, /banana integration, zone layout) — those are unique to claude-obsidian and live above kepano's primitive. Install kepano: `claude plugin marketplace add kepano/obsidian-skills`. --- ## Default Canvas `wiki/canvases/main.canvas` If it does not exist, create it: ```json { "nodes": [ { "id": "title", "type": "text", "text": "# Visual Reference\n\nDrop images, PDFs, and notes here.", "x": -400, "y": -300, "width": 400, "height": 120, "color": "6" }, { "id": "zone-default", "type": "group", "label": "General", "x": -400, "y": -140, "width": 800, "height": 400, "color": "4" } ], "edges": [] } ``` --- ## Operations ### open / status (`/canvas` with no args) 1. Check if `wiki/canvases/main.canvas` exists. 2. If yes: read it, count nodes by type, list all group node labels (zone names). Report: "Canvas has N nodes: X images, Y text cards, Z wiki pages. Zones: [list]" 3. If no: create it with the starter structure above. Report: "Created main.canvas with a General zone." 4. Tell user: "Open `wiki/canvases/main.canvas` in Obsidian to view." --- ### new (`/canvas new [name]`) 1. Slugify the name: lowercase, spaces → hyphens, strip special chars. 2. Create `wiki/canvases/[slug].canvas` with the starter structure, title updated to `# [Name]`. 3. Add entry to `wiki/overview.md` under a "## Canvases" subsection (append after the Current State section). Do not modify `wiki/index.md`. It uses a fixed section schema (Domains, Entities, Concepts, Sources, Questions, Comparisons). 4. Report: "Created wiki/canvases/[slug].canvas" --- ### add image (`/canvas add image [path or url]`) **Resolve the image:** - If URL (starts with `http`): download with `curl -sL [url] -o _attachments/images/canvas/[filename]` Derive filename from URL path, or use `img-[timestamp].jpg` if unclear. - If local path outside vault: `cp [path] _attachments/images/canvas/` - If already vault-relative: use as-is. Create `_attachments/images/canvas/` if it doesn't exist. **Detect aspect ratio:** Use `python3 -c "from PIL import Image; img=Image.open('[path]'); print(img.width, img.height)"` or `identify -format '%w %h' [path]`. See `references/canvas-spec.md` for the full aspect ratio → canvas size table (7 ratios including 4:3, 3:4, ultra-wide). Do not use an inline table here. The spec is the single source of truth for sizing. **Position using auto-layout** (see Auto-Positioning section below). **Append node to canvas JSON and write.** Report: "Added [filename] to [zone] zone at position ([x], [y])." --- ### add text (`/canvas add text [content]`) Create a text node: ```json { "id": "text-[timestamp]", "type": "text", "text": "[content]", "x": [auto], "y": [auto], "width": 300, "height": 120, "color": "4" } ``` Position using auto-layout. Write and report. --- ### add pdf (`/canvas add pdf [path]`) Same as add image. Obsidian renders PDFs natively as file nodes. - Copy to `_attachments/pdfs/canvas/` if outside vault. - Fixed size: width=400, height=520. - Report page count if you can determine it. --- ### add note (`/canvas add note [wiki-page]`) 1. Search `wiki/` for a file matching the page name (case-insensitive, partial match ok). 2. Use the vault-relative path as the `file` field. - Use `"type": "file"` (not `"type": "link"`): `.md` files use file nodes, not link nodes. - `"type": "link"` takes a `url: "https://..."`: it is for web URLs only. 3. Create a file node: width=300, height=100. 4. Position using auto-layout. ```json { "id": "note-[timestamp]", "type": "file", "file": "wiki/concepts/LLM Wiki Pattern.md", "x": [auto], "y": [auto], "width": 300, "height": 100 } ``` --- ### zone (`/canvas zone [name] [color]`) 1. Read canvas JSON. 2. Find max_y: `max(node.y + node.height for all nodes) + 60`. Use 280 if no nodes (leaves room above the starter title node). 3. Create a group node: ```json { "id": "zone-[slug]", "type": "group", "label": "[name]", "x": -400, "y": [max_y], "width": 1000, "height": 400, "color": "[color or '3']" } ``` Valid colors: `"1"`=red `"2"`=orange `"3"`=yellow `"4"`=green `"5"`=cyan `"6"`=purple Write and report. --- ### list (`/canvas list`) 1. `glob wiki/canvases/*.canvas` 2. For each canvas: read JSON, count nodes by type. 3. Report: ``` wiki/canvases/main.canvas . 14 nodes (8 images, 3 text, 2 file, 1 group) wiki/canvases/design-ideas.canvas. 42 nodes (30 images, 4 text, 8 groups) ``` --- ### from banana (`/canvas from banana`) (if the banana-claude plugin is installed) 1. Check `wiki/canvases/.recent-images.txt` first (session log of newly written images). 2. If not found or empty: use `find` with correct precedence (parentheses required. Without them `-newer` only binds to the last `-name` clause): ```bash python3 -c "import time,os; open('/tmp/ten-min-ago','w').close(); os.utime('/tmp/ten-min-ago',(time.time()-600,time.time()-600))" find _attachments/images -newer /tmp/ten-min-ago \( -name "*.png" -o -name "*.jpg" \) ``` Note: `/banana` is an optional external skill not shipped in this plugin. If the user has it installed, the `.recent-images.txt` log will be populated. If not, the `find` command above is the fallback. 3. If still none: show the 5 most recently modified images. 4. Present list: "Found N recent images: [list]. Add to canvas? Which zone? (zone name / 'new [name]' / 'skip')" 5. On confirmation: add each using the add image logic. --- ## Auto-Positioning Algorithm Read `references/canvas-spec.md` for the full coordinate system. ```python def next_position(canvas_nodes, target_zone_label, new_w, new_h): # Find zone group node zone = next((n for n in canvas_nodes if n.get('type') == 'group' and n.get('label') == target_zone_label), None) if zone is None: # No zone: place below all content max_y = max((n['y'] + n.get('height', 0) for n in canvas_nodes), default=-140) return -400, max_y + 60 zx, zy = zone['x'], zone['y'] zw, zh = zone['width'], zone['height'] # Nodes inside this zone inside = [n for n in canvas_nodes if n.get('type') != 'group' and zx <= n['x'] < zx + zw and zy <= n['y'] < zy + zh] if not inside: return zx + 20, zy + 20 rightmost_x = max(n['x'] + n.get('width', 0) for n in inside) next_x = rightmost_x + 40 if next_x + new_w > zx + zw: # New row max_row_y = max(n['y'] + n.get('height', 0) for n in inside) return zx + 20, max_row_y + 20 # Same row: align to the top of all existing nodes in the zone current_row_y = min(n['y'] for n in inside) return next_x, current_row_y ``` --- ## ID Generation Read the canvas, collect all existing IDs. Never reuse one. Safe ID pattern: `[type]-[content-slug]-[full-unix-timestamp]` Use the full Unix timestamp (10 digits) to avoid collisions in batch operations. Examples: `img-cover-1744032823`, `text-note-1744032845`, `zone-branding-1744032901` If a collision is detected (ID already exists in the canvas), append `-2`, `-3`, etc. --- ## Session Log (optional hook) If `wiki/canvases/.recent-images.txt` exists, append any new image path written to `_attachments/images/` during this session (one path per line, keep last 20). `/canvas from banana` reads this file first, making it instant without filesystem search. --- ## Banana Integration (if the banana-claude plugin is installed) After any `/banana` run in the same session, if the user says "add to canvas" or "put on canvas", treat it as `/canvas from banana`. When `/banana` finishes generating images, suggest: > "Add generated images to canvas? Run `/canvas from banana`" --- ## Summary 1. Read canvas-spec.md before editing any canvas JSON. 2. Always read the canvas file before writing. Parse existing nodes to avoid ID collisions and calculate auto-positions. 3. Create `_attachments/images/canvas/` for downloaded/copied images. 4. Update `wiki/index.md` when creating new canvases. 5. Report position and zone after every add operation. ## See Also For standalone visual production (12 templates, 6 layout algorithms, AI generation, presentations), see [claude-canvas](https://github.com/AgriciDaniel/claude-canvas). This skill handles wiki-scoped visual boards. claude-canvas handles full-featured canvas orchestration for any project. --- ## How to think (10-principle mapping) When working on this skill, apply the 10-principle loop. See [`skills/think/SKILL.md`](../think/SKILL.md) for the canonical framework. | # | Principle | Application here | |---|-----------|-------------------| | 1 | OBSERVE (ext) | Which images, PDFs, notes belong on this canvas? Read each before adding. | | 2 | OBSERVE (int) | Am I aestheticizing or actually communicating? Pretty canvases that don't inform are noise. | | 3 | LISTEN | The user's mental model of how these items relate. The canvas should mirror that, not impose another. | | 4 | THINK | Layout, group hierarchy, edge structure. Spatial reasoning matters; arbitrary positions confuse. | | 5 | CONNECT (lat) | Edges between canvas nodes reveal hidden structure not visible in the linear wiki. | | 6 | CONNECT (sys) | JSON Canvas 1.0 spec + Obsidian-native rendering + banana skill for AI image gen. | | 7 | FEEL | A canvas should be readable at first glance, not a maze of arrows. | | 8 | ACCEPT | Not every project needs a canvas. Admit when prose is enough. | | 9 | CREATE | Write the `.canvas` JSON with stable IDs and sensible positions. | | 10 | GROW | Which canvases get reopened? Which are abandoned? That signal informs canvas-worthiness over time. | [View on SkillFed](https://skillfed.io/AgriciDaniel/claude-obsidian/canvas) · [View on GitHub](https://github.com/AgriciDaniel/claude-obsidian)