org-draw

Seamless drawing into org-mode.

org-draw lets you draw inside Org-mode using any device with a web browser and have the result land in org-mode buffer as an inline, re-editable, portable figure.

Get started

Add to MELPA

straight.el + use-package

(use-package org-draw
  :straight (org-draw :type git :host github :repo "larrasket/org-draw"
                      :files ("*.el" ("web" "web/canvas.html")))
  :commands (org-draw org-draw-edit org-draw-setup))

Doom Emacs

In ~/.doom.d/packages.el:

(package! org-draw
  :recipe (:host github :repo "larrasket/org-draw"
           :files ("*.el" ("web" "web/canvas.html"))))

In ~/.doom.d/config.el:

(use-package! org-draw
  :commands (org-draw org-draw-edit org-draw-setup))

elpaca + use-package

(use-package org-draw
  :ensure (:host github :repo "larrasket/org-draw"
           :files ("*.el" ("web" "web/canvas.html")))
  :commands (org-draw org-draw-edit org-draw-setup))

Usage

M-x org-draw copies the receiver URL to your clipboard. Open it on your machine or any device in your network.

If other people share your network and you don’t want them reaching the server, set org-draw-require-pairing to non-nil. Then the page shows a code-entry screen and org-draw-setup prints a single-use 6-digit code to type in (it expires after 5 wrong attempts).

The drawing surface is tldraw. tldraw is loaded from a CDN, the device needs internet access the first time it opens the page (on an offline network the page shows a clear message instead of a blank screen).

Customization

• org-draw-port (default 8777)
• org-draw-directory (default "figures")
• org-draw-file-name-function (default org-draw-default-file-name)
• org-draw-insert-attr-width (default nil) when set to an integer pixel width, org-draw inserts a #+ATTR_ORG: :width N line above the link to a newly created figure, so it displays at a fixed width inline. Leave it nil to skip the ATTR line entirely.
• org-draw-require-pairing (default nil) whether a browser must enter a 6-digit code before it can draw. Off by default (any browser on your LAN can receive drawings). Set to non-nil on a shared network to require pairing.
• org-draw-token-file (default <user-emacs-directory>/org-draw-tokens) where paired-device tokens are stored (only used when org-draw-require-pairing is on)
• org-draw-figure-background (default transparent) the background baked behind a figure’s ink in the exported PNG. transparent keeps true ink colors and shows the figure against your org buffer’s background (so a white pen shows in a dark theme and a black pen in a light theme); or set it to white, dark, or a CSS color string to bake that behind every figure.
• org-draw-web-canvas-file path to the web canvas HTML served at /canvas (defaults to web/canvas.html shipped with the package).
• org-draw-open-browser (default nil) when non-nil, org-draw and org-draw-edit open the canvas in a browser on the machine running Emacs (via browse-url), so you can draw right there instead of on another device.
• org-draw-copy-url (default t) copy the receiver URL to the kill-ring on org-draw-setup and on the first org-draw of a session. Set to nil to stop copying; the URL is still echoed and listed in the setup buffer.
• org-draw-web-open-function (default nil) a custom opener for the per-session /canvas URL; takes precedence over org-draw-open-browser. Set it to a function (e.g. one that targets a specific browser); it is called with the URL.

Keybindings

No keys are bound by default. A suggested set for Org buffers:

(with-eval-after-load 'org
  (define-key org-mode-map (kbd "C-c d d") #'org-draw)
  (define-key org-mode-map (kbd "C-c d e") #'org-draw-edit)
  (define-key org-mode-map (kbd "C-c d s") #'org-draw-setup))

Or with use-package:

(use-package org-draw
  :bind (:map org-mode-map
         ("C-c d d" . org-draw)
         ("C-c d e" . org-draw-edit)
         ("C-c d s" . org-draw-setup)))

License

GPL-3.0-or-later. See LICENSE.