logseq-whiteboards

LogSeq Whiteboards

LogSeq Whiteboards are infinite spatial canvases stored as .edn (Extensible Data Notation) files. Built on a custom fork of tldraw, they combine freeform drawing with LogSeq's knowledge graph — allowing you to place pages, blocks, shapes, connectors, images, and web embeds together on a visual canvas.

File Location

Whiteboard files are stored in the whiteboards/ directory of a LogSeq graph:

my-graph/
├── journals/
├── pages/
├── whiteboards/          ← Whiteboard .edn files here
│   ├── My Diagram.edn
│   └── Project Board.edn
├── assets/               ← Images referenced by whiteboards
└── logseq/
    └── config.edn        ← Can customize :whiteboards-directory

The directory name can be changed in config.edn via :whiteboards-directory.

EDN File Structure

Every whiteboard .edn file has two top-level sections: :blocks (shapes) and :pages (canvas metadata).

{:blocks (
  ;; Each shape is a block with :logseq.tldraw.shape properties
  {:block/created-at 1728698317371
   :block/properties
   {:ls-type :whiteboard-shape
    :logseq.tldraw.shape
    {:type "text"
     :id "unique-uuid"
     :point [100 200]
     :size [300 50]
     ;; ... shape-specific properties
     }}
   :block/updated-at 1728698317371}
  ;; More shape blocks...
  )
 :pages (
  ;; One page entry per whiteboard
  {:block/uuid #uuid "page-uuid-here"
   :block/properties
   {:ls-type :whiteboard-page
    :logseq.tldraw.page
    {:id "page-uuid-here"
     :name "whiteboard-name"
     :bindings {}
     :nonce 1
     :assets []
     :shapes-index ("shape-id-1" "shape-id-2" "shape-id-3")}}
   :block/type "whiteboard"
   :block/name "whiteboard-name"
   :block/original-name "Whiteboard Name"
   :block/created-at 1728698317371
   :block/updated-at 1728698317371}
  )}

Shape Types

LogSeq whiteboards support 8 shape types:

Type	Description
"text"	Text labels and paragraphs
"box"	Rectangles with optional labels
"line"	Lines and arrows (connectors)
"pencil"	Freehand drawings
"image"	Images (references assets)
"logseq-portal"	Embedded LogSeq pages or blocks
"youtube"	Embedded YouTube videos
"iframe"	Embedded web pages

---

Common Shape Properties

All shapes share these properties within :logseq.tldraw.shape:

Property	Type	Description
:type	String	Shape type (see table above)
:id	String	Unique UUID for this shape
:point	[x y]	Position (top-left corner) on canvas
:size	[width height]	Dimensions in pixels
:index	Integer	Z-order (rendering layer, higher = on top)
:scale	[sx sy]	Scale factors (usually [1 1])
:opacity	Number	Opacity 0.0 to 1.0
:rotation	Number	Rotation in radians (0 = no rotation)
:parentId	String	Parent shape ID (page ID for top-level shapes)
:nonce	Integer	Timestamp for change tracking

---

Text Shape

Text labels and headings on the canvas.

{:logseq.tldraw.shape
 {:type "text"
  :id "uuid-here"
  :point [100 200]
  :size [300 50]
  :text "Hello World"
  :fontSize 32               ;; Font size in pixels
  :fontFamily "'Inter'"      ;; Font family (CSS)
  :fontWeight 700            ;; 400 = normal, 700 = bold
  :italic false              ;; Italic text
  :lineHeight 1.2            ;; Line height multiplier
  :isSizeLocked true         ;; Size auto-adjusts to text
  :scaleLevel "lg"           ;; "xs", "sm", "md", "lg", "xl"
  :padding 4                 ;; Internal padding
  :stroke "var(--tl-foreground, #000)"
  :fill "#ffffff"
  :noFill true               ;; true = transparent background
  :strokeType "line"
  :strokeWidth 2
  :borderRadius 0
  :index 0
  :scale [1 1]
  :opacity 1
  :parentId "page-uuid"
  :nonce 1664366266517}}

Scale levels control default font sizes:

Level	Typical fontSize
"xs"	12
"sm"	16
"md"	20
"lg"	32
"xl"	48

---

Box Shape

Rectangles for containers, cards, and labeled shapes.

{:logseq.tldraw.shape
 {:type "box"
  :id "uuid-here"
  :point [0 0]
  :size [1071 578]
  :label ""                  ;; Text label inside box (can be empty)
  :stroke "#ababab"          ;; Border color
  :fill "var(--ls-secondary-background-color)"  ;; Fill color
  :noFill false              ;; false = filled, true = transparent
  :strokeType "line"         ;; "line" or "dashed"
  :strokeWidth 2
  :borderRadius 2            ;; Corner rounding in pixels
  :fontSize 20               ;; Label font size
  :fontWeight 400
  :italic false
  :rotation 0
  :index 1
  :scale [1 1]
  :opacity 1
  :parentId "page-uuid"
  :nonce 1664366266231}}

---

Line Shape (Connectors and Arrows)

Lines connect shapes with optional arrowheads and labels.

{:logseq.tldraw.shape
 {:type "line"
  :id "uuid-here"
  :point [2824 284]          ;; Base point (origin for handles)
  :stroke "var(--ls-primary-text-color, #000)"
  :fill "var(--ls-secondary-background-color)"
  :noFill true
  :strokeType "line"         ;; "line" or "dashed"
  :strokeWidth 1
  :label ""                  ;; Text label on the line
  :fontSize 20
  :fontWeight 400
  :italic false
  :handles                   ;; Start and end points (relative to :point)
  {:start
   {:id "start"
    :canBind true            ;; Can snap to other shapes
    :point [0 0]             ;; Relative position [x y]
    :bindingId nil}          ;; UUID of bound shape (nil = unbound)
   :end
   {:id "end"
    :canBind true
    :point [52 0]            ;; End point relative to base
    :bindingId nil}}
  :decorations               ;; Arrowheads
  {:start nil                ;; nil or "arrow"
   :end "arrow"}             ;; nil or "arrow"
  :index 28
  :scale [1 1]
  :opacity 1
  :parentId "page-uuid"
  :nonce 1664464964296}}

Decorations: Set :start and/or :end to "arrow" for arrowheads. Use nil for no arrowhead.

Bindings: When a line connects to a shape, :bindingId references the bound shape's ID. The :bindings map in the page metadata tracks these connections.

---

Pencil Shape (Freehand Drawing)

Freehand strokes from the pencil tool.

{:logseq.tldraw.shape
 {:type "pencil"
  :id "uuid-here"
  :point [212 160]           ;; Base position
  :points [[0 0 0.5]]       ;; Array of [x y pressure] points (relative)
  :stroke ""                 ;; Stroke color (empty = theme default)
  :fill ""
  :noFill true
  :strokeType "line"
  :strokeWidth 2
  :scaleLevel "md"
  :isComplete true           ;; true when stroke is finished
  :index 0
  :scale [1 1]
  :opacity 1
  :parentId "page-uuid"
  :nonce 1730788259525}}

Each point in :points is [x y pressure] where:

• x, y are relative to the shape's :point
• pressure is pen pressure (0.0 to 1.0, typically 0.5 for mouse)

---

Image Shape

Images reference assets stored in the graph's assets/ directory.

{:logseq.tldraw.shape
 {:type "image"
  :id "uuid-here"
  :point [136 200]
  :size [260 105]
  :assetId "asset-uuid"     ;; References asset in page's :assets array
  :isAspectRatioLocked true ;; Preserve aspect ratio on resize
  :isLocked false            ;; Prevent accidental moves
  :objectFit "fill"          ;; "fill", "contain", "cover"
  :clipping 0                ;; Clipping amount
  :index 0
  :scale [1 1]
  :opacity 1
  :parentId "page-uuid"
  :nonce 1770432010158}}

Assets are defined in the page's :assets array:

:assets [
  {:id "asset-uuid"
   :type "image"
   :src "../assets/image_1770432010069_0.png"  ;; Relative path
   :size [520 210]}]                            ;; Original dimensions

---

LogSeq Portal Shape

The unique LogSeq feature — embed pages or blocks from your graph directly onto the whiteboard.

{:logseq.tldraw.shape
 {:type "logseq-portal"
  :id "uuid-here"
  :point [256 168]
  :size [400 141]
  :blockType "P"             ;; "P" = page portal, "B" = block portal
  :pageId "PageName"         ;; Page name (for page portals)
  ;; :blockId "block-uuid"  ;; Block UUID (for block portals)
  :collapsed false           ;; true = show only title
  :collapsedHeight 0         ;; Height when collapsed
  :compact false             ;; Compact display mode
  :isAutoResizing true       ;; Auto-resize to fit content
  :stroke ""
  :fill ""
  :noFill false
  :strokeType "line"
  :strokeWidth 2
  :borderRadius 8
  :scaleLevel "md"
  :index 2
  :scale [1 1]
  :opacity 1
  :parentId "page-uuid"
  :nonce 1731296148685}}

Portal types:

• Page portal (blockType: "P"): Uses :pageId — embeds an entire page
• Block portal (blockType: "B"): Uses :blockId — embeds a single block and its children

Portals render live LogSeq content. Editing the portal edits the actual page/block.

---

YouTube Shape

Embed YouTube videos on the canvas.

{:logseq.tldraw.shape
 {:type "youtube"
  :id "uuid-here"
  :point [7383 321]
  :size [283 159]
  :url "https://www.youtube.com/watch?v=VIDEO_ID"
  :rotation 0
  :index 49
  :scale [1 1]
  :parentId "page-uuid"
  :nonce 1664531347941}}

---

IFrame Shape

Embed any web page on the canvas.

{:logseq.tldraw.shape
 {:type "iframe"
  :id "uuid-here"
  :point [7730 321]
  :size [282 158]
  :url "https://logseq.com/"
  :rotation 0
  :index 50
  :scale [1 1]
  :parentId "page-uuid"
  :nonce 1664531425980}}

---

Page Metadata

The :pages section contains canvas-level metadata:

{:block/uuid #uuid "page-uuid"
 :block/properties
 {:ls-type :whiteboard-page
  :logseq.tldraw.page
  {:id "page-uuid"
   :name "whiteboard-name"        ;; Lowercase page name
   :bindings {}                    ;; Shape-to-shape binding map
   :nonce 1                        ;; Change counter
   :assets [                       ;; Image assets used by shapes
     {:id "asset-uuid"
      :type "image"
      :src "../assets/filename.png"
      :size [width height]}]
   :shapes-index ("id1" "id2")}}  ;; Ordered list of shape IDs
 :block/type "whiteboard"
 :block/name "whiteboard-name"     ;; Lowercase
 :block/original-name "Whiteboard Name"  ;; Original case
 :block/created-at 1728698317371
 :block/updated-at 1728698317371}

:shapes-index controls the order shapes are listed. This is a list of shape IDs.

:bindings tracks connections between lines and shapes when :bindingId is set on line handles.

:assets stores metadata for images used by image shapes. The :src path is relative to the graph root.

---

Color Values

Shapes support these color formats:

Format	Example
Hex color	"#ababab", "#ffffff"
CSS variable	"var(--ls-primary-text-color, #000)"
Named color	"gray"
Empty (theme default)	""

Common CSS variables:

• var(--ls-primary-text-color, #000) — primary text
• var(--ls-secondary-background-color) — secondary background
• var(--tl-foreground, #000) — tldraw foreground

---

Coordinate System

• Origin: Top-left of the canvas (can extend into negative coordinates)
• X axis: Increases to the right
• Y axis: Increases downward
• :point is the top-left corner of each shape
• :size is [width height] in pixels
• :handles on lines are relative to the line's :point

---

Complete Example

A minimal whiteboard with a box, text label, and an arrow:

{:blocks (
  {:block/created-at 1700000000000
   :block/properties
   {:ls-type :whiteboard-shape
    :logseq.tldraw.shape
    {:type "box"
     :id "box-1"
     :point [100 100]
     :size [200 100]
     :stroke "#ababab"
     :fill "var(--ls-secondary-background-color)"
     :noFill false
     :strokeType "line"
     :strokeWidth 2
     :borderRadius 8
     :label "My Box"
     :fontSize 20
     :fontWeight 400
     :italic false
     :rotation 0
     :index 0
     :scale [1 1]
     :opacity 1
     :parentId "page-1"
     :nonce 1700000000000}}
   :block/updated-at 1700000000000}
  {:block/created-at 1700000000001
   :block/properties
   {:ls-type :whiteboard-shape
    :logseq.tldraw.shape
    {:type "text"
     :id "text-1"
     :point [100 50]
     :size [200 30]
     :text "Hello Canvas"
     :fontSize 24
     :fontFamily "'Inter'"
     :fontWeight 700
     :italic false
     :lineHeight 1.2
     :isSizeLocked true
     :scaleLevel "lg"
     :padding 4
     :stroke ""
     :fill ""
     :noFill true
     :strokeType "line"
     :strokeWidth 2
     :borderRadius 0
     :index 1
     :scale [1 1]
     :opacity 1
     :parentId "page-1"
     :nonce 1700000000001}}
   :block/updated-at 1700000000001}
  {:block/created-at 1700000000002
   :block/properties
   {:ls-type :whiteboard-shape
    :logseq.tldraw.shape
    {:type "line"
     :id "arrow-1"
     :point [350 150]
     :stroke ""
     :fill ""
     :noFill true
     :strokeType "line"
     :strokeWidth 1
     :label ""
     :fontSize 20
     :fontWeight 400
     :italic false
     :handles
     {:start
      {:id "start"
       :canBind true
       :point [0 0]
       :bindingId nil}
      :end
      {:id "end"
       :canBind true
       :point [100 0]
       :bindingId nil}}
     :decorations
     {:end "arrow"}
     :index 2
     :scale [1 1]
     :opacity 1
     :parentId "page-1"
     :nonce 1700000000002}}
   :block/updated-at 1700000000002})
 :pages (
  {:block/uuid #uuid "00000000-0000-0000-0000-000000000001"
   :block/properties
   {:ls-type :whiteboard-page
    :logseq.tldraw.page
    {:id "page-1"
     :name "my-diagram"
     :bindings {}
     :nonce 1
     :assets []
     :shapes-index ("box-1" "text-1" "arrow-1")}}
   :block/type "whiteboard"
   :block/name "my-diagram"
   :block/original-name "My Diagram"
   :block/created-at 1700000000000
   :block/updated-at 1700000000002})}

Tips

1. EDN format — Uses Clojure-style syntax: {} for maps, () for lists, [] for vectors, :keyword for keys
2. UUIDs — Shape IDs are typically UUID v1 format (time-based), page UUIDs use #uuid "..." reader literal
3. parentId — Top-level shapes set :parentId to the page's UUID string
4. Assets — Images must have both an entry in :assets (page level) and a shape with matching :assetId
5. Portals are live — LogSeq portal shapes render actual graph content; edits sync bidirectionally
6. CSS variables — Use LogSeq CSS variables for theme-aware colors
7. Whiteboard = page — Every whiteboard is also a LogSeq page with :block/type "whiteboard"

References

• LogSeq Whiteboards Announcement
• tldraw SDK (base canvas library)
• LogSeq GitHub
• EDN Format Specification