31:T722,md`# Downloading and Embedding Notebooks

**tl;dr** *[Notebooks can be embedded and customized](http://ashkenas.com/breakout/) anywhere on the web (or off it).* So, you’ve written your magnum opus: an awesome notebook full of splendor and delight. Now, the problem is — How do you display it on your website? How do you integrate its nifty charts into your web app? How do you save it to your laptop, to show to your grandmother who lives in the internet-free woods of Nova Scotia? As you’ve probably noticed by now, Observable notebooks are a little bit different than the regular old JavaScripts you know and love. They execute in order of dependency and data flow rather than in a linear sequence of statements, and contain strange and marvelous reactive primitives, like [viewof](https://beta.observablehq.com/@mbostock/a-brief-introduction-to-viewof) and [mutable](https://beta.observablehq.com/@jashkenas/introduction-to-mutable-state). Luckily, Observable provides an open-source [runtime](https://github.com/observablehq/notebook-runtime), which stitches together a notebook’s cells into a dependency graph and brings them to life through evaluation; a [standard library](https://github.com/observablehq/notebook-stdlib), which provides helpful functions for working with HTML, SVG, generators, files and promises among [other useful sundries](https://beta.observablehq.com/@mbostock/standard-library); and an [inspector](https://github.com/observablehq/notebook-inspector), which implements the default strategy for rendering DOM and JavaScript values into a live web page — although you’re free to write your own. We’ll use the Observable runtime to render notebooks outside of observablehq.com.`32:T571,md`Observable also provides a copy of your notebook as an installable npm module, in gzipped tarball flavor.

Right-clicking and copying that link, will get you something that looks like this:
\`https://api.observablehq.com/@jashkenas/my-neat-notebook.tgz?key=ed62e16955cdc185\` You can use this URL to install a notebook into your project with **npm**, **Yarn** or the JavaScript package manager of your choice: \`\`\` npm i https://api.observablehq.com/@jashkenas/my-neat-notebook.tgz?key=ed62e16955cdc185 yarn add https://api.observablehq.com/@jashkenas/my-neat-notebook.tgz?key=ed62e16955cdc185 \`\`\` This will install the notebook as a package under its published name ("my-neat-notebook"). Notebooks are versioned with every change that you make, and requests to the Observable API for the ES Module or Tarball will receive the latest published or shared version. If you want to lock your request to a specific version, you can add the version number of any published or shared version of your notebook to the URL: \`\`\` https://api.observablehq.com/@jashkenas/my-neat-notebook@42.js?key=ed62e16955cdc185 https://api.observablehq.com/@jashkenas/my-neat-notebook@365.tgz?key=ed62e16955cdc185 \`\`\``33:[] 2f:{"title":"Downloading and Embedding Notebooks","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":62,"value":"iconHeader(\"Notebooks as ES Modules\", ``)","pinned":false,"hidden":false,"mode":"ojs"},{"id":106,"value":"md`After you share or publish a notebook, a copy of it, compiled to JavaScript, may be downloaded or linked as an [ES module](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/). Click the **Download code** link in a notebook’s menu to retrieve the URL for your notebook.\n\n

\n\nThe URL will look something like this:\n\n\\`https://api.observablehq.com/@jashkenas/my-neat-notebook.js?key=ed62e16955cdc185\\`\n\nNote the **access key** appended to the URL. This key is private to you, unique to each of your notebooks, and allows you to control where your notebooks are embedded. For the moment, if you need to reset an access key, send an email to \\`support@observablehq.com\\`, and we’ll sort you out.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":291,"value":"md`\nUsing this ES module version of your notebook, you can run and render cells in any web or JavaScript environment.\n\nHere’s a basic example script that renders every cell in a notebook into an empty HTML page:\n\n\\`\\`\\`html\n\n\\`\\`\\``","pinned":false,"hidden":false,"mode":"ojs"},{"id":281,"value":"md`\\`Runtime.load()\\` takes two or three arguments: a **notebook** module, an optional **builtins** object (which defaults to the Observable [standard library](https://github.com/observablehq/notebook-stdlib)), and an **observer callback**, which is invoked for each cell in your notebook, and may choose to return an **observer object** that can receive or render values as the cell is computed.\n\nDefine your **observer object** with three optional methods: \n\n**pending()** is called whenever the cell is reevaluated.\n\n**fulfilled(value)** is passed the resolved value of the cell, whenever the evaluation has finished.\n\n**rejected(error)** is passed the error when a cell fails to resolve for any reason.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":311,"value":"md`\nAs a first example, let’s build our own version of \\`Inspector.into()\\`, still using the [notebook-inspector](https://github.com/observablehq/notebook-inspector) library:\n\n\\`\\`\\`js\nRuntime.load(notebook, (cell) => {\n var div = document.createElement(\"div\");\n document.body.appendChild(div);\n return new Inspector(div);\n});\n\\`\\`\\``","pinned":false,"hidden":false,"mode":"ojs"},{"id":316,"value":"md`\nHere's an example of an observer callback that doesn't touch the DOM at all, instead logging all evaluation to the console:\n\n\\`\\`\\`js\nRuntime.load(notebook, (cell) => {\n return {\n pending: () => console.log(\\`\\${cell.name} is running...\\`),\n fulfilled: (value) => console.log(cell.name, value),\n rejected: (error) => console.error(error)\n };\n});\n\\`\\`\\``","pinned":false,"hidden":false,"mode":"ojs"},{"id":320,"value":"md`\nFinally, here's an example of an observer callback that inserts just a single cell from your notebook into the page:\n\n\\`\\`\\`js\nRuntime.load(notebook, (cell) => {\n if (cell.name === \"chart\") {\n return {\n fulfilled: (value) => {\n document.getElementById(\"chart\").appendChild(value);\n }\n };\n }\n});\n\\`\\`\\``","pinned":false,"hidden":false,"mode":"ojs"},{"id":465,"value":"md`*Nota bene:* On observablehq.com, each cell in your notebook is evaluated eagerly by default, because each cell is visible on the page. With embedded notebooks, cells for which you do not provide an *observer* will not be evaluated (unless other cells depend on them). This gives you the flexibility to evaluate as much or as little of your notebook as you like, but may also make things appear broken if your notebook uses a lot of side effects. To force evaluation of a cell, just return an observer object (or \\`true\\`) from the observer callback.\n\n\\`\\`\\`js\nRuntime.load(notebook, (cell) => {\n if (cell.name === \"canvas\") {\n return {fulfilled: (value) => $(\"#canvas\").append(value)};\n } else {\n // Force evaluation of all the other cells in the notebook.\n return true;\n }\n});\n\\`\\`\\``","pinned":false,"hidden":false,"mode":"ojs"},{"id":64,"value":"iconHeader(\"Notebooks as npm modules\", ``)","pinned":false,"hidden":false,"mode":"ojs"},{"id":108,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":188,"value":"demo = md`## ✨ Live Demonstrations ✨\n\nAs an off-site example of an embedded notebook in action, check out http://ashkenas.com/breakout. It loads the runtime and [this Observable notebook](https://beta.observablehq.com/@jashkenas/breakout), rendering values from four of the notebook cells into the page: the **game canvas**, the **\"New Game\" button**, the **current score**, and the **high score**.\n\n\n

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":435,"value":"md`As a second, more minimal, example: [this CodePen](https://codepen.io/jashkenas/pen/gzZXPG) embeds a [simple notebook](https://beta.observablehq.com/d/e8186dc6a68b5179) that exposes a single \\`tick\\` cell, incrementing every second.\n\nAs a third example, [Philippe Rivière](https://beta.observablehq.com/@fil) wrote a brief tutorial that demonstrates embedding [this notebook on Tissot’s indicatrix](https://beta.observablehq.com/@fil/tissots-indicatrix) into a [Jekyll blog post](https://visionscarto.net/observable-jekyll/).\n\nAnd finally, as an arcane demonstration of the dark arts of recursive embedding, we can use the Observable environment to demonstrate the brainbending reality of a [notebook embedding *itself*](https://beta.observablehq.com/@jashkenas/ouroboros-a-notebook-embeds-itself). Wow!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":450,"value":"md`We’re hoping to continue working to make notebook embedding more useful over time — with your help. If you have interesting use cases, publishing workflows, npm module ideas, website embed techniques, or just want to talk about anything else you’d like to see embedded notebooks do, please join the conversation on [talk.observablehq.com](https://talk.observablehq.com/).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":82,"value":"function iconHeader(title, svg) {\n return html`\n

${title}

`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":15,"value":"md`*Thanks for the pile of books, [ClipArt ETC](http://etc.usf.edu/clipart/54200/54238/54238_book_pile.htm).*`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}