1c:{"title":"Upgrading to Notebooks 2.0","cells":[{"id":19,"value":"# Upgrading to Notebooks 2.0\n\nThe new Observable does its best to be backwards compatible with notebooks written in the old editor. With a few exceptions, notebooks should work as before. But if want to try updating your notebooks to take advantage of the [new system](https://new.observablehq.com/d/96643af8378d5694), this guide is for you.\n\nThere are two categories of changes to consider:\n1. [Upgrading the standard library](#upgrading-the-standard-library)\n2. [Using vanilla JavaScript](#using-vanilla-java-script)\n\nWe’ll cover them in turn. If you have questions, or find a compatibility issue, feel free to discuss on [the Observable forum](https://talk.observablehq.com/) — and remember the Observable Agent can also help you upgrade!","pinned":false,"hidden":false,"mode":"md"},{"id":24,"value":"## Upgrading the standard library\n\nOpen the ${icon(\"dependencies\")} **Dependencies** panel from the right sidebar. The icon shows a red dot for notebooks using the 2018 standard library. You’ll see two options:\n\n- 2026\n- 2018 (deprecated)\n\nSelect _2026_ to immediately see how your notebook renders under the new standard library. In most notebooks everything works immediately. But you might notice some changes in the way Markdown, HTML and SVG are rendered, or code that ceases to work because it relies on a given version of a recommended library.","pinned":false,"hidden":false,"mode":"md"},{"id":25,"value":"### Markdown\n\nThe 2018 version of Markdown cells and `md` uses [marked](https://marked.js.org/). The 2026 version uses [markdown-it](https://github.com/markdown-it/markdown-it), which conforms to the [CommonMark specification](https://spec.commonmark.org/). Notably, CommonMark does not interpret Markdown syntax within HTML blocks; for example, `

This is **bold**.

` does _not_ render in bold and instead shows literal asterisks. [Typographic replacements](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs) are also enabled in 2026: straight quotes (`'`) are promoted to curly quotes (`’`), `--` becomes an en-dash (`–`), `...` becomes an ellipsis (…), _etc._","pinned":false,"hidden":false,"mode":"md"},{"id":8,"value":"### html and svg\n\nIn the 2018 standard library, the `html` & `svg` tagged template literals simply concatenate HTML source. Hence, if you interpolate a string such as `

hello $\\{\"world\"}

`, the string is interpolated as HTML and the resulting output includes italics. This behavior is potentially surprising and unsafe when applied to arbitrary input. The 2026 standard library's `html` and `svg` in contrast are built on [Hypertext Literal](https://github.com/observablehq/htl), which automatically escapes interpolated values appropriately based on context, so an interpolated `\"world\"` renders literally as `world`. Note that HTML cells in the 2018 standard library already used Hypertext Literal (as `htl.html`), and hence their behavior is unchanged in the latest version.","pinned":false,"hidden":false,"mode":"md"},{"id":26,"value":"### require and resolve\n\nThe 2018 standard library predates the widespread adoption of [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), favoring [asynchronous module definitions (AMD)](https://github.com/d3/d3-require) for loading libraries via the `require()` function. The 2026 library instead favors standard ES modules and [import statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). Before:\n```ojs\nd3 = require(\"d3\")\n```\n\nAfter:\n```js\nimport * as d3 from \"npm:d3\";\n```\n\nSee the [imports](./notebooks-2-0-system-guide#imports) section in the system guide for details. In the 2026 library, `require()` has been removed. While you can still import d3-require explicitly to use require, you are strongly encouraged to use standard imports.","pinned":false,"hidden":false,"mode":"md"},{"id":16,"value":"## Using vanilla JavaScript\n\nNotebooks 1.0 used an idiosyncratic JavaScript syntax called _Observable JavaScript_ or OJS. Notebooks 2.0 instead favor vanilla JavaScript and TypeScript syntax for better portability and interoperability.\n\nTo upgrade to `js`, there are three forms of `ojs` cell to consider and that require slightly different treatment. An Observable JavaScript cell can be an _expression cell_ consisting of a single JavaScript expression (such as `1 + 2`), a _block cell_ consisting of any number of JavaScript statements (such as `add(1, 2);`), or an _import cell_ importing another notebook.","pinned":false,"hidden":false,"mode":"md"},{"id":22,"value":"### Expression cells\n\nNamed expression cells in `ojs` can be converted into standard variable declarations, typically using `const`. So this:\n\n```ojs\nfoo = 42\n```\n\nbecomes this:\n\n```js\nconst foo = 42;\n```\n","pinned":false,"hidden":false,"mode":"md"},{"id":17,"value":"Variable declarations in `js` cells don’t implicitly display. To display the value of a variable (such as `foo` above), call `display` explicitly. The `display` function returns its argument, so you can write:\n\n```js\nconst bar = display({hello: \"world\"});\n```\n\nJavaScript cells allow multiple variable declarations in the same code block, so you can coalesce multiple `ojs` cells from a notebook into a single `js` cell. But note that there’s no [implicit `await`](/d/96643af8378d5694#promises) when referring to a variable declared in the same code block --- so beware of promises.","pinned":false,"hidden":false,"mode":"md"},{"id":5,"value":"$1e","pinned":false,"hidden":false,"mode":"md"},{"id":27,"value":"### Imports\n\nObservable JavaScript cells can import another notebook like so:\n\n```ojs\nimport {BarChart} from \"@d3/bar-chart\"\n```\n\nThe vanilla JavaScript equivalent is a standard import declaration using the `observable:` protocol:\n\n```js\nimport {BarChart} from \"observable:@d3/bar-chart\";\n```\n\nAlternatively, you can use import attributes to declare an Observable import, allowing you to import reactive JavaScript from an arbitrary URL, including self-hosted notebooks:\n\n```js\nimport {BarChart} from \"https://api.observablehq.com/@d3/bar-chart.js?v=4\" with {type: \"observable\"};\n```\n\nNote: Notebooks 2.0 does not support Observable JavaScript's [`import with` syntax](https://observablehq.com/documentation/notebooks/imports#import-with), which allowed injecting symbols into the imported notebook, even in Observable JavaScript cells. We recommend rewriting the imported notebook to export a standard function instead.","pinned":false,"hidden":false,"mode":"md"},{"id":18,"value":"$1f","pinned":false,"hidden":false,"mode":"md"},{"id":6,"value":"### Views\n\nIn `ojs` cells, the nonstandard [`viewof` operator](https://observablehq.com/@observablehq/views) is used to declare a reactive value that is controlled by a user interface element such as a range input. In `js` cells, the `view` function performs the equivalent task with vanilla syntax. So this:\n\n```ojs\nviewof gain = Inputs.range([0, 11], {value: 5, step: 0.1, label: \"Gain\"})\n```\n\ncan be converted to:\n\n```js\nconst gain = view(Inputs.range([0, 11], {value: 5, step: 0.1, label: \"Gain\"}));\n```\n\nIn other words: replace `viewof` with `const`, and then wrap the input declaration with a call to `view`. The `view` function both displays the given input and returns the corresponding value generator so you can define a top-level reactive value.","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"### Mutables\n\nIn `ojs` cells, the nonstandard [`mutable` operator](https://observablehq.com/@observablehq/mutable) is used to declare a reactive value that can be assigned from another cell. In vanilla `js`, the `Mutable` function performs the equivalent task, with an explicit setter function. So this:\n\n```ojs\nmutable foo = 42\n```\n\n```ojs\n{\n mutable foo = 0;\n}\n```\n\ncan be converted to:\n\n```js\nconst foo = Mutable(42);\nconst setFoo = (x) => (foo.value = x);\n```\n\n```js\nsetFoo(0);\n```\n\nNote that `setFoo` must be declared in the same code block as `foo`, and that outside of that block, `foo` represents the value; any code that depends on `foo` will update reactively after `setFoo` is invoked.","pinned":false,"hidden":false,"mode":"md"},{"id":32,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":31,"value":"import {keys, buttons} from \"observable:@observablehq/keys\";\nimport {icon} from \"observable:@observablehq/icons\";","pinned":false,"hidden":false,"mode":"ts"}],"files":"$W20","stdlib":"2"}