Observable Desktop User guide

---

Installing

Observable Desktop currently requires macOS 15+ and Apple Silicon.

1. Download and open the disk image (.dmg).
2. Copy Observable Desktop to your Applications folder.
3. Double-click to open the application.

---

Signing in

Observable Desktop requires an Observable account. If you don’t already have one, you can create one when you sign in.

1. Open Observable Desktop, then click Open browser.
2. If needed, sign in to your Observable account, or create an account.
3. Click Authorize the desktop app.
4. Close the Success window to return to Observable Desktop.
5. Wait a few seconds for Observable Desktop to sign in.

---

Creating and opening notebooks

Notebooks are stored as local .html files. New notebooks are not saved until you save them, but subsequent edits are saved automatically.

1. Choose File > New ⌘N to open a new, blank notebook.
2. Make any edits, as desired.
3. Choose File > Save ⌘S to save your notebook.

1. Choose File > Open ⌘O to open a notebook.

---

Opening and closing cells

Notebooks are comprised of small programs, or cells, which can be written in Markdown, HTML, JavaScript, and other languages. A cell’s source code is visible below the cell’s output if the cell is pinned or focused.

1. Click the left gutter to focus the cell.
2. Edit the cell as desired.
3. Click the left gutter to blur the cell and run the new code.

1. enter ↩︎ to select the cell, then enter ↩︎ again to focus it.
2. Edit the cell as desired.
3. esc ⎋ to select the cell, then esc ⎋ again to blur it.

---

Pinning cells

Pinned cells stay open even when they are not focused. JavaScript cells are pinned by default, but other cells default to unpinned. If a cell doesn’t display anything, it will stay open regardless of whether it is pinned.

1. Click the left gutter to focus the cell.
2. Click the pin icon in the toolbar.
3. Click the close icon in the toolbar to blur the cell.

---

Inserting and deleting cells

You can split existing cells or merge them together. You can also insert new, blank JavaScript cells. You can delete cells after selecting them. Empty cells are deleted automatically on blur.

1. Split a cell at the caret with option-enter ⌥↩︎.
2. Merge a cell into the previous cell with option-delete ⌥⌫.
3. Split a cell at the caret with option-shift-enter ⌥⇧↩︎.
4. Marge a cell into the next cell with control-option-D ⌃⌥D.

1. Insert a JavaScript cell below with command-enter ⌘↩︎.
2. Insert a JavaScript cell above with shift-command-enter ⇧⌘↩︎.

1. Insert a JavaScript cell by clicking the inserter.
2. Insert a Markdown cell by option ⌥-clicking the inserter.

1. Focus a cell, say by clicking the editor.
2. Select the cell with esc ⎋.
3. Delete the cell with D.
4. Clear the selection with esc ⎋.

---

Cell modes

Cells can be written in JavaScript, Markdown, HTML, and several other languages. You can cycle between the primary modes when a cell is empty, or use the mode menu or edit menu to change the mode.

1. Insert a new, empty cell.
2. Change the cell mode with down ↓ or up ↑.

1. Focus a cell, say by clicking on the editor.
2. Change the cell mode to JavaScript with command-1 ⌘1.
3. Change the cell mode to Markdown with command-2 ⌘2.
4. Change the cell mode to HTML with command-3 ⌘3.

1. Focus a cell, say by clicking on the editor.
2. Change the cell mode using the mode menu.

---

Running cells

You can run cells while editing. If you edit a cell, it will run automatically when blurred. When a cell has edits that have not yet been run (a “dirty” cell), the cell will have a dark blue border and the play button will be highlighted.

1. Focus a cell, say by clicking the editor.
2. Click the play button to run the cell.

1. Focus a cell, say by clicking the editor.
2. Run the cell with shift-enter ⇧↩︎.

---

Navigating between cells

There are a variety of keyboard shortcuts for fast navigation between cells.

1. Focus a cell, say by clicking the editor.
2. Focus the cell below with option-tab ⌥⇥.
3. Focus the cell above with shift-option-tab ⌥⇧⇥.

1. Select a cell, say with enter ↩︎.
2. Select the cell below with J.
3. Select the cell above with K.
4. Focus the cell with enter ↩︎.

---

Loading data

After saving a notebook, you can open a local file in the same folder using FileAttachment.

1. Open a saved notebook, or save the current one.
2. Insert a JavaScript cell.
3. Call FileAttachment, passing in the relative path to the file.
4. Call the appropriate method to load the data, such as csv() or json().

---

Exporting images

You can export graphics as SVG or PNG.

1. Focus or select a cell.
2. Click the export menu in the toolbar.
3. Click Export PNG or Export SVG.

---

Next steps

If you’re comfortable with the Desktop editor and are ready to learn about authoring notebooks, please see the Notebooks system guide.