Canvas

The canvas feature in Discourse Graph provides an interactive visual workspace for creating and connecting discourse nodes and relations. Built on top of tldraw, it allows you to visually map out discourse structures with drag-and-drop functionality, adding other visual elements like texts, scribbles, embeddings, and images.

Creating a new canvas

Using the command palette

1. Open the command palette (Cmd/Ctrl + P)
2. Search for “Create new Discourse Graph canvas”
3. Press Enter to create a new canvas

The canvas will be created in your configured canvas folder (default: Discourse Canvas/) with a timestamp-based filename like Canvas-2025-01-15-1430.md.

Opening and viewing canvas

Opening a canvas

1. Open the file of the canvas
2. In case the file is still in markdown format, you can open the canvas mode by either

Using the command palette

Or click on the canvas icon at the top right corner

Discourse nodes

You can add discourse nodes to a canvas in several ways. Most flows open the Create discourse node modal, where you can create a new node or search for and select an existing one.

Add a discourse node to canvas

1. Click the Discourse Graph icon in the bottom toolbar
2. In the panel on the right, click a node type to select it (or drag a node type onto the canvas)
3. Click on the canvas where you want the node
4. In the Create discourse node modal, enter a title, confirm the node type, and click Confirm The new node appears on the canvas as a discourse node card linked to the note that was created.

• You can also search for existing node from this modal and insert it to the canvas

Add an existing node

By dragging onto the canvas

Only notes that are already discourse nodes (with a configured nodeTypeId in frontmatter) can be dropped. If the same node is already on the canvas, the existing card is selected instead of duplicating it.

From the file explorer

1. In the Obsidian file explorer, drag a discourse node note onto the canvas
2. The node is added at the drop location

From the editor

When a Discourse Graph canvas is open, internal links in Live Preview show a small drag handle (⠿) after the link.

1. In a note, find a wikilink or markdown link to a discourse node (for example [[CLM - My claim]])
2. Drag using the handle next to the link
3. Drop onto the canvas

The handle appears for [[wikilinks]] and [markdown links](path.md) that point to notes in your vault. It does not appear on image embeds (![[...]]).

Convert text or image shapes into a node

Turn tldraw text or image shapes into discourse nodes without leaving the canvas:

1. Select a text or image shape on the canvas
2. Right-click the shape
3. Choose a node type from the Convert to submenu
4. In the modal, edit the title (text is pre-filled; images start with an empty title) or search for an existing node
5. Click Confirm — the shape is replaced with a discourse node card

Discourse relations

Create new relations between nodes

• Click the discourse node icon in the toolbar
• Click the type of relations you want to create between two nodes
• Click and drag the arrow from the source node to target node

• Alternatively, you can select the dots that show up when you click a node, then start dragging to the destination node to create a new relation

Note: The relation type selected must be compatible between the source and target nodes. Otherwise, you will receive a relation tool error. To update the setting on what relation types are possible between two kinds of discourse nodes, you can change the setting Relation types setting

Adding existing relations

• Click on the discourse node you’re trying to add existing relations of
• Click on the “Relations” button that pops up. You’ll see a panel showing all the relations that this node has
• Click on the ’+’ or ’-’ to add these relations to the canvas
  • For relations whose target discourse node isn’t on canvas yet, it will be added to the canvas along with the relation

Canvas Features

Key figures

You can choose to show the first image of discourse nodes of certain type. To change the setting on whether this first image show up, you can edit it in the Node Type Setting

Then you will see the image show up if any is present in the file.

Open discourse node files

• To open a discourse node to the side panel, you can press Shift + Click, or click on the sidebar icon when hover on discourse node.
• To open file to a new tab, you can press Cmd + click on the file

Auto-save

• Changes are automatically saved to the markdown file
• No manual save required
• File updates preserve the markdown structure and block references
• An open canvas also watches its file, so changes written by another tab, another device, or a sync service are merged in as they arrive. See Avoiding data loss for the cases this cannot cover.

Export Options

• Markdown View: Switch to see the underlying markdown structure
• SVG Export: Export canvas as SVG image (via tldraw)
• PNG Export: Export canvas as PNG image (via tldraw)

Avoiding data loss

Editing in more than one place

An open canvas holds its own copy of the canvas in memory and writes the whole canvas back to the markdown file shortly after each change. It also watches that file, so a change written by another tab, another device, or a hand edit is merged into your open canvas as it arrives.

That merge works item by item — each shape, and each relation between nodes — and each item is merged as a whole rather than field by field. It is not full conflict resolution. If the same item is changed in two places at once, the version that reached the file first wins, and the later change to it is discarded. The rest of the canvas is kept.

To keep your work safe:

• Edit a canvas in one place at a time. Close duplicate tabs, splits, and popout windows showing the same canvas.
• Let sync finish before you start editing on a second device, and check that the canvas shows your latest work before you change anything.
• Do not hand-edit the canvas data block, whether or not the canvas is open.

Use only one sync service

Running more than one sync service over the same vault — for example Obsidian Sync alongside iCloud Drive, Dropbox, or Google Drive — can duplicate, corrupt, or delete files, and canvases are no exception. Obsidian calls this double-syncing and does not support it.

If your vault sits inside a cloud storage folder, move it out or turn off the other service. See Troubleshoot Obsidian Sync  for Obsidian’s own guidance.

Troubleshooting

Common Issues

Canvas Won’t Load:

• Check that the file has proper frontmatter with tldr-dg: true
• Verify the JSON data block is properly formatted
• Try switching to markdown view and back to canvas view

Relations Won’t Connect:

• Ensure the node types allow the relation type you’re trying to create
• Check your discourse relation configuration in settings
• Verify both nodes are valid discourse nodes

Canvas Is Missing Recent Changes:

• Check whether the same canvas is open in another tab, split, or window, and close the duplicates
• On a synced vault, confirm sync has finished on every device
• Check your sync service for a conflicted copy or version history of the file, which may still hold the missing work
• Confirm only one sync service is running over the vault (see Use only one sync service)
• If you saw the notice “Canvas file contains invalid data; your latest changes were not saved.”, the data block could not be read — check the file for a damaged or hand-edited data block

Performance Issues:

• Consider splitting large canvases into multiple smaller ones
• Close other resource-intensive applications

Search Not Working:

• Verify nodes have proper frontmatter with nodeTypeId
• Check that the Obsidian metadata cache is up to date
• Try restarting Obsidian to refresh the cache

Getting Help

If you encounter issues with the canvas feature, reach out to our dev team via Slack