EtherPK User Docs

Drawings

A drawing is a picture that sits among the lines of a document. EtherPK draws with Excalidraw, which is built in, so you have nothing to install. A drawing holds shapes, arrows, text and freehand lines in a hand-drawn style, drawn with a mouse, a finger or a pen. You can switch drawings off on a device. See Extensions for more information.

A drawing shows as a picture until you press it to edit it. Your changes save into the document as you draw, so there is no save button. The drawing is stored as text inside the document, with no separate file, so it syncs, moves and exports along with the document.

Insert a drawing

To insert a drawing:

  1. Put the caret on a line of its own, or on an empty bullet.
  2. Type /draw or /excalidraw.
  3. In the slash menu, select Excalidraw (drawing).

If the caret was on an empty bullet, the drawing takes the bullet's line. The new drawing opens ready to draw: in the document on the desktop layout with a mouse or a trackpad, and over the whole window on a phone or a touch screen.

A drawing is not offered in a table, a protected document or a document that cannot be written. If you try to insert a drawing where it cannot go, you see "The drawing couldn't go there. Put the caret on a line of its own and try again."

Edit a drawing in the document

On the desktop layout with a mouse or a trackpad, you edit a drawing where it sits in the document. On a phone or a touch screen, such as a tablet, it opens over the whole window, so a finger can still scroll the document.

To start editing, press the picture, or focus it with the keyboard and press Enter or Space. The picture becomes the editor. A toolbar above it holds Done, Full window and Open in tab, with Edit as text and Delete set apart from them.

To stop editing, select Done or press anywhere outside the drawing. Either way your drawing is saved and the picture comes back. Pressing inside a dialog or menu that Excalidraw opens keeps the drawing open. You can edit only one drawing at a time across all your open documents, so starting on another saves the first and turns it back into a picture.

While you edit, Ctrl+Z and Ctrl+Y (Cmd+Z and Cmd+Y on a Mac) undo and redo in Excalidraw's own history for the drawing.

When you are not editing, Edit as text and Delete are also in a menu over the picture. Its button (…) sits in the top right corner and appears when you point at the drawing or focus it with the keyboard. On a touch screen the button is always shown. From the keyboard, press Enter or Down to open the menu, then use the arrow keys to move through it. Escape closes the menu and returns focus to the button.

The caret normally passes over a drawing as one block, and the drawing's lines stay hidden. Edit as text shows them in the document and puts the caret on the first line. When the caret moves off them, the picture comes back.

In a document that cannot be written there is no toolbar or menu, and pressing the picture opens the drawing over the window for you to look at.

Delete a drawing

Delete removes the drawing at once, without asking, because Ctrl+Z (Cmd+Z on a Mac) in the document brings it back. A message then says "Drawing deleted. Press Ctrl+Z (Cmd+Z on a Mac) in the document to bring it back." A drawing on a bullet leaves the bullet behind, empty.

Excalidraw's tools

You draw with Excalidraw's own tools for shapes, arrows, text and freehand lines. EtherPK switches off the image tool, web embeds and Excalidraw's AI features, which leaves two commands in the Excalidraw menu: change the canvas background and clear the canvas. While you draw, Escape leaves the current tool.

A drawing is light in both of EtherPK's themes, the editor and the picture alike, and shows the colours it stores.

Import a drawing from excalidraw.com

A share link from excalidraw.com looks like https://excalidraw.com/#json=<id>,<key>. Paste one on an empty line or an empty bullet with nothing selected, and an import card replaces it. You get no card in a task, a table, the frontmatter or a protected document, or when you paste the link as plain text with Ctrl+Shift+V (Cmd+Shift+V on a Mac). The card works on every layout, phones included.

Nothing is fetched until you select Import this drawing from excalidraw.com. The app then writes the drawing into the document and removes the link and its key, so the drawing no longer depends on excalidraw.com. If the import fails, the card says why and keeps the link so you can try again. Open on excalidraw.com shows the original in a new browser tab.

You can also copy shapes on excalidraw.com and paste them onto an empty line to make a drawing. Drawings in EtherPK hold no images, so an import or a paste leaves images out, and a message tells you, such as "The drawing was imported without its image. Drawings in EtherPK hold no images."

Chinese, Japanese and Korean text

The EtherPK download does not include Excalidraw's handwriting font for Chinese, Japanese and Korean. The app downloads it the first time a drawing needs it and keeps it for offline use from then on. If you are offline before that, text in those languages shows in a font from your system.

Open a drawing in a tab or the full window

While you edit a drawing in the document, you can give it more room. Open in tab moves the editing to a tab of its own and puts the picture back in the document, and the changes you make in the tab reach the document. Full window makes the drawing fill the EtherPK window. See Tabs And Panes for more information.

The full window has a heading that names the document, such as "Drawing: Garden", and a Close button in the top right corner. Escape stays with Excalidraw, which uses it to leave a tool. A tab and the full window have no toolbar and no menu button, and Ctrl+Z and Ctrl+Y use the drawing's own history there too.

Drawings on a touch screen

On a phone, and on a tablet or any device whose main pointer is a finger or a pen, a drawing is never edited in its place in the document, where it would take the finger that scrolls the page. Tap it and it opens over the whole window, ready to draw. A drawing you insert from the slash menu opens there too. Close, in the top right corner, takes you back to the document. In a document that cannot be written, the drawing opens as a picture that you can pinch to zoom.

In a narrow window, such as a phone's, Excalidraw uses its own phone layout, with its tools along the top and its menu, Undo and Redo along the bottom. See EtherPK On A Phone for more information.

When a pen touches a drawing, Excalidraw turns on its pen mode, where only the pen draws and a finger does not. Its pen mode button turns it off again.

How drawings are stored

In the document, a drawing is a fenced code block named excalidraw.drawing. Its first line names the drawing and holds its background colour. Each element after it, a shape, an arrow, a text or a line, has a line of its own. So when two devices draw on the same drawing at once, their changes merge element by element. See Synced Graphs for more information.

A drawing is part of the document text, but Search does not find the words or lines in it.

In a protected document a drawing is protected text like the rest, so its lines are encrypted with the document. You see the lines instead of a picture, a drawing is not offered in the slash menu, and a tab or the full window says the drawing cannot be shown. See Protected Documents for more information.

When a block holding a drawing links to a page, Backlinks shows the picture, never the lines, light in both themes.

A published site shows each drawing as a picture, never its lines, light, with its fonts inside the picture.

If drawings are switched off on the device you publish from, the site leaves them out and the publish report warns you.

The Headless Client draws the same pictures with a browser, so a publish that includes drawings is refused until diagrams setup has installed Chromium. See Publishing Your Notes As A Website for more information.

  • Code Maths And Diagrams
    • Extensions keep their data in extension blocks, whose language word is the extension id, a dot and a name, such as excalidraw.drawing. When the extension is switched on, and installed if it comes from the Extension Directory, it draws the block in place. The extension reads every line of the block, so change those lines only through it. The drawings that come with EtherPK are extension blocks. See Drawings for more information.
    • Only its own extension can publish an extension block. If the extension is switched off or not installed, the block is left out and the publish report names the document. The Headless Client runs no extensions, so it leaves out every extension block except a drawing, which it can draw (Drawings).
  • Document Syntax
  • Extensions
  • Planned Features
    • | Searching inside extension blocks, such as drawings | Search, the find box, search by meaning and a published site's search all skip extension blocks. | Drawings, Extensions, Find And Replace |
  • Using AI Agents With Your Notes
    • Publishing a site with a diagram, map picture or drawing is refused without this setup, because a browser draws them, and nothing is written. A dry run of that site is also refused. You do not need the setup to serve a graph, to publish a site without them, or to publish from EtherPK in your browser. See Browser for diagrams below, and Code Maths And Diagrams, Maps and Drawings for more information.