2b:null 2c:["$","title",null,{"children":"Notebooks user guide | Observable | Observable"}] 31:T82f,## Editing cells Click in the left gutter to focus the cell editor. Before you begin typing, you can press ${buttons("Down")} and ${buttons("Up")} to cycle through cell modes. You can always change the mode by clicking the mode tag in the upper right of the editor, such as `ts` or `md`, to open the cell menu. The available cell modes are: - **TypeScript** (`ts`), for general coding; types are stripped, not checked. - **Markdown** (`md`), for writing prose. - **HTML** (`html`), for more complex layouts and formatting. - **SQL** (`sql`), for database queries. - **TeX** (`tex`), for mathematical expressions. - **DOT** (`dot`), for diagrams. - **JavaScript** (`js`), for vanilla JavaScript without type-stripping. - **Observable JavaScript** (`ojs`), for backwards compatibility, equivalent to JavaScript cells in notebooks 1.0. Press ${buttons("Shift-Enter")} to commit and run the cell. Press ${buttons("Cmd-Enter")} to insert a new cell below the current cell, or ${buttons("Shift-Cmd-Enter")} to insert a new cell above. Press ${buttons("Alt-Enter")} to split the cell at the caret, or ${buttons("Shift-Alt-Enter")} to split the cell upward at the caret. Press ${buttons("Alt-Delete")} at the start of a cell to merge it into the previous one, or ${buttons("Shift-Alt-Delete")} at the end of a cell to merge it into the next one. Press ${buttons("Alt-Tab")} to focus the cell below. Press ${buttons("Shift-Alt-Tab")} to focus the cell above. Press ${buttons("Escape")} to go into cell selection mode. In that mode, use ${buttons("j")} and ${buttons("k")} to move the selection focus up and down, ${buttons("x")} to select and deselect the focused cell, and ${buttons("Enter")} to exit selection mode and return focus to the given cell editor. Press ${buttons("Shift-Cmd-I")} to format the cell with Prettier. For more about writing notebooks, see the [system guide](https://new.observablehq.com/@observablehq/notebooks-2-0-system-guide). For help converting old notebooks to take advantage of notebooks 2.0, see the [upgrade guide](https://observablehq.com/d/342634064e732825).32:T52f,## Sharing and publishing Some notebooks are private internal documents meant only for your team. In other cases, you may work on a notebook alone for months before it’s ready to publish to the world. There are three possible access levels: - ${icon("private")} **Private** (default): only you or your workspace can view the notebook. - ${icon("unlisted")} **Unlisted**: the notebook is visible to anyone with the URL, but is not publicly listed. - ${icon("public")} **Public**: the notebook is visible to everyone and is listed on your profile and in the [public notebook listings](https://new.observablehq.com/public). Publish your notebook or otherwise change the access level in ${icon("settings")} **Settings**.

${await FileAttachment("Settings.png").image({width: 240})}

When you create a notebook in a team workspace, it can always be viewed or edited by anyone else in the workspace. When multiple team members are editing the same notebook at the same time, note that you cannot yet see each other’s live multiplayer cursors. If you edit a cell that someone else has also edited since you loaded the notebook, we will try to merge your edits. If we cannot merge automatically, then you will see both sets of edits and can reconcile them manually.33:[{"id":"2d67ed86b3dd9c619f47b61d818438c6a79716338fb5cc6a120c95af5940960d6fc958d2d0fb5400b812064baced60d69dd61ed6b34e08f4d7999800c2160c27","href":"https://static.observableusercontent.com/files/2d67ed86b3dd9c619f47b61d818438c6a79716338fb5cc6a120c95af5940960d6fc958d2d0fb5400b812064baced60d69dd61ed6b34e08f4d7999800c2160c27","name":"Agent.png","type":"image/png","lastModified":1781154733790.864,"size":196130},{"id":"1584fcbba28d7b5604cd24cbdb0af2bdd2291bc3e32c760a33483000f6390ed177025a43b7e18fe0146824428d3581e90c17f02f5573563b942dd385a0f08be1","href":"https://static.observableusercontent.com/files/1584fcbba28d7b5604cd24cbdb0af2bdd2291bc3e32c760a33483000f6390ed177025a43b7e18fe0146824428d3581e90c17f02f5573563b942dd385a0f08be1","name":"Settings.png","type":"image/png","lastModified":1788285315484,"size":52668},{"id":"af3e96277efd7c778d0260d895dd39e9e61e87b2f960cfa1791623982a4f8f7bf2194a2b92665b70f4d97466a7656b77ff1821191cfd00f3a62c84815e2f5d19","href":"https://static.observableusercontent.com/files/af3e96277efd7c778d0260d895dd39e9e61e87b2f960cfa1791623982a4f8f7bf2194a2b92665b70f4d97466a7656b77ff1821191cfd00f3a62c84815e2f5d19","name":"Notebook interface.webp","type":"image/webp","lastModified":1788284913860,"size":139072}] 2f:{"id":"480a471b02ce8556","slug":"notebooks-user-guide","title":"Notebooks user guide","thumbnail":"b202236400f8aa03dd5de1c2896429257441a1389372305d782778dda9b68f2b","access_level":"public","create_time":"$D2026-06-10T18:47:09.872Z","update_time":"$D2026-09-01T17:57:43.043Z","view_time":null,"first_public_time":"$D2026-06-12T18:07:49.676Z","fork":false,"stars":8,"starred":false,"owner":{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024"},"version":557,"publish_version":557,"role":null,"authored":false,"authors":[{"type":"individual","id":"0bb2842b01e0c652","login":"tophtucker","name":"Toph Tucker","avatar_url":"https://avatars-next.observableusercontent.com/3706c31a8f9c59bb716c022c04b9c073144cd1368b78ac85f49139be6c93c34e","tier":null},{"type":"individual","id":"074c414ad1d825f5","login":"mbostock","name":"Mike Bostock","avatar_url":"https://avatars-next.observableusercontent.com/7dbba99ced40bd5ab8013c99b1a11da61231bce321ba1148a9d16ad0f121550a","tier":null}],"members":[{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","role":"editor"},{"type":"individual","id":"0bb2842b01e0c652","login":"tophtucker","name":"Toph Tucker","avatar_url":"https://avatars-next.observableusercontent.com/3706c31a8f9c59bb716c022c04b9c073144cd1368b78ac85f49139be6c93c34e","tier":null,"role":"editor"}],"comments":[{"id":"003ce8ae64f33209","reply_to_id":null,"content":"why `await`? shouldn't we write those instead as \n\n```ts\nconst image = FileAttachment(\"image.jpg\").image({width: 100});\n```\n\nor just\n```ts\nFileAttachment(\"image.jpg\").image({width: 100})\n```","create_time":"$D2026-06-11T11:11:49.335Z","update_time":null,"resolved":false,"user":{"type":"individual","id":"45a379fcfcb14253","login":"fil","name":"Fil","avatar_url":"https://avatars-next.observableusercontent.com/d5b1777907117a2bdf2a07eb98600d7a9beb21639fde42b9753e95c88c7731a6","tier":null}},{"id":"9e60c6af1a7587e0","reply_to_id":"003ce8ae64f33209","content":"And we can replace await FileAttachment(\"image.jpg\").url() with FileAttachment(\"image.jpg\").href, which I’ve done.","create_time":"$D2026-07-07T20:15:10.615Z","update_time":null,"resolved":false,"user":{"type":"individual","id":"074c414ad1d825f5","login":"mbostock","name":"Mike Bostock","avatar_url":"https://avatars-next.observableusercontent.com/7dbba99ced40bd5ab8013c99b1a11da61231bce321ba1148a9d16ad0f121550a","tier":null}}],"custom_thumbnail":true,"trashed":false,"subscribed":null,"forks":2,"collection":{"id":"24eb6ec5e74aa0c6","slug":"documentation","title":"Documentation","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"type":"notebook","body":{"title":"Notebooks user guide","cells":[{"id":0,"value":"# Notebooks user guide\n\nNotebooks are the heart of Observable. To create a notebook, click ${icon(\"new-notebook\")} in the upper right. A notebook is a list of _cells_ of text or code. Begin typing Markdown in the initial cell, or click ${icon(\"plus\")} to insert a new cell.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":38,"value":"FileAttachment(\"Notebook interface.webp\").image()","pinned":false,"hidden":false,"mode":"ts","author":"$undefined","summary":"$undefined"},{"id":49,"value":"The **workspace menu** lets you go to your current workspace, another workspace, or the public workspace. If you’re creating a new notebook and haven’t edited it yet, the workspace menu lets you change where it’ll be created.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":50,"value":"The **notebook header** tells you the access level, last edited date, notebook authors, and fork parent. On the right, you can star or fork the notebook, or see others who have.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":45,"value":"The **sidebar** has, at the top, toggles for several panels of additional controls:\n\n- ${icon(\"dataflow\")} **Dataflow** is coming soon.\n- ${icon(\"files\")} **Files** lets you upload, replace, rename, and delete files.\n- ${icon(\"dependencies\")} **Dependencies** lets you pick the version of the standard library: 2018 (deprecated) or 2026.\n- ${icon(\"comments\")} **Comments** lets you see comments others have left on the notebook. You cannot yet post new comments.\n- ${icon(\"version-history\")} **Version history** is coming soon. The new editor saves versions but does not yet let you browse them.\n- ${icon(\"settings\")} **Settings** shows if you have permission to edit the notebook. It lets you publish the notebook, delete it, set the access level, or set the slug.\n\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":54,"value":"And, at the bottom:\n\n- ${icon(\"ai\")} **AI** ${buttons(\"/\")} toggles the Observable agent panel.\n- ${icon(\"pencil\")} **Enable tinkering** shows when you don’t have permission to edit.\n- ${icon(\"pencil\")} **Enable editing** shows when you can edit but are not yet an author.\n- ${icon(\"spinner\")} **Saving changes** shows when you commit a cell.\n- ${icon(\"error\")} **Warning** shows if saving failed.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":52,"value":"Additional commands appear only if editing the notebook is enabled, either because you are an author or because you have ${icon(\"pencil\")} enabled editing manually.\n\nThe **cell inserter** ${buttons(\"Cmd-Enter\")} adds a new cell in the given spot. New cells are TypeScript by default. Hold ${buttons(\"Alt\")} and click for a Markdown cell. You can cycle cell modes by pressing ${buttons(\"Down\")}.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":51,"value":"The **cell toolbar** shows commands for modifying the currently selected cells. (To enter selection mode and use these keyboard shortcuts, press ${buttons(\"x\")} with no cell focused, or ${buttons(\"Escape\")} with a cell focused.)\n\n- **Run** ${buttons(\"Shift-Enter\")} commits and runs the cell.\n- **Export** ${buttons(\"e\")} lets you export a PNG or SVG of the output of the cell.\n- **Pin** ${buttons(\".\")} toggles the whether the code is shown.\n- **Move up** ${buttons(\"Alt-Up\")} moves the cell up.\n- **Move down** ${buttons(\"Alt-Down\")} moves the cell down.\n- **Duplicate** ${buttons(\"Alt-Shift-Down\")} creates a copy of the cell below it.\n- **Delete** ${buttons(\"d\")} removes the cell.\n- **Select** ${buttons(\"x\")} toggles whether the cell is selected.\n- **Clear selection** ${buttons(\"Escape\")} removes any focus or selection.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":53,"value":"The **cell menu** can be opened by clicking the cell mode tag in the upper right of an editor. It lets you switch modes, toggle whether the cell’s code is pinned open, and toggle whether the cell’s output is hidden.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":37,"value":"$31","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":20,"value":"## AI agent\n\nThe AI agent can help you understand notebooks you’re viewing, help you edit and fix bugs, or create whole notebooks from scratch.\n\nClick ${icon(\"ai\")} in the bottom right to toggle the AI panel. You can also press ${buttons(\"/\")} to open it and ${buttons(\"Escape\")} to close it. Type a prompt and click ${icon(\"send\")} or press ${buttons(\"Enter\")}. Stop the agent by clicking the spinning ${icon(\"thinking\")}.\n\nFor every message you send, the agent sees the context of the contents of the notebook. At its discretion, it can inspect live runtime values, too. It can add, edit, move, and delete cells.\n\n

\n ${await FileAttachment(\"Agent.png\").image({width: 320})}\n

\n\nBefore it runs any code, it waits for your permission. You can allow ${buttons(\"Cmd-Y\")}, deny ${buttons(\"Cmd-Z\")}, or allow all requests from then on ${buttons(\"Shift-Cmd-Y\")}.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":30,"value":"## Files\n\nTo upload a file, click ${icon(\"files\")} **Show files** in the sidebar and then ${icon(\"upload\")} **Add file**. Once a file is uploaded, hover over it and click ${icon(\"dots\")} to replace, rename, delete, or copy the usage code to paste into a cell.\n\nUse a file in a notebook with the `FileAttachment` function. Different file types offer different methods, each of which returns a promise. For example:\n\n```ts\nFileAttachment(\"data.csv\").csv({typed: true})\n```\n\n```ts\nFileAttachment(\"data.json\").json()\n```\n\n```ts\nFileAttachment(\"data.xlsx\").xlsx()\n```\n\n```ts\nFileAttachment(\"city.shp\").arrayBuffer()\n```\n\n```ts\nFileAttachment(\"notes.md\").text()\n```\n\n```ts\nFileAttachment(\"image.jpg\").image({width: 100})\n```\n\n```html\n

\n```","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":59,"value":"$32","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":57,"value":"## Authors\n\nWhen you edit a notebook, you are added to its authors. In the workspace view, notebook listings show the first author; looking at a notebook, the header shows all authors. Public notebooks you’ve authored appear on your public profile.\n\nWhen you open a notebook which you have permission to edit but haven’t edited, it will begin in read-only mode until you ${icon(\"pencil\")} enable editing in the bottom right.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":60,"value":"## Support\n\nFor help building notebooks and using the product, please post in the [forum](https://talk.observablehq.com/c/help/6), where both community members and Observable staff would be happy to chat.\n\nFor customer support or inquiries about enterprise use, please contact support@observablehq.com.\n\nNotebooks 2.0 is an early beta. We welcome all feedback and would appreciate any bug reports. We are currently working on rebuilding improved versions of features that existed in notebooks 1.0, including private notebook imports, database connectors, commenting, and the minimap, as well as new features we are excited to discuss soon.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":61,"value":"---\n## Appendix","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":39,"value":"import {keys, buttons} from \"observable:@observablehq/keys\"\nimport {icon} from \"observable:@observablehq/icons\"","pinned":false,"hidden":true,"mode":"ts","author":"$undefined","summary":"$undefined"}],"files":"$W33","stdlib":"2","titling":"auto"}} 30:"$2f:body"