Setting up
Observable Notebooks
Online or on the Desktop

using Observable, you can develop your projects in one or both of two ways: on the Observable platform or, especially for MacOS, using the Observable Desktop app locally. If you develop online, you will eventually download your notebooks to your local computer in order to control the production of a website (known as a ‘static site’) for your project

Working Online

If you read the introductory, home page, then you’ve already signed up for a free Observable account. On the site you can begin to work in one of two ways: (1) you can create a notebook, or (2) you can start a ‘chat’.

  1. If you create a notebook, you’ll see a blank page with one ‘cell’, a Markdown cell with “Untitled” in it, waiting for you to give your notebook an initial, working title. When you make the edit and type Shift-return to execute the cell, you will see the Markdown code rendered, displayed as an HTML element in your notebook.

You’ll go on to explore and experiment, checking out the documents as necessary, to make cells of different kinds, especially cells with programming code in them, typically JavaScript.

You’ll also start using the language model assistant to help you generate and manipulate both code and text.

  1. If you start a chat, what you are doing is making a notebook while transacting with a language model. Chats are incremental (you can’t go back and revise) but this is, potentially, a very expressive and powerful way to start a project. You are generating cells as you continue the chat. At a certain point you may have done something you want to keep and work on differently, in the form of an actual notebook. At this point, hit the Fork button (top right, to left of the star) and the chat becomes a notebook.

More on all this in consultation with your instructor and colleagues.

Working Locally

If you have a MacOS computer, you can work with notebooks (not chats), locally, and these are the instructions for setting this up.

Download and Install Observable Desktop

If you use a Mac computer, then please download and use Observable Desktop.

Go to https://observablehq.com/notebook-kit/desktop and then scroll down to the Download link. (If you have time and interest, watch the video.) Install the app.

If you use a Windows PC or other computer, and you still want to work locally, then you will be using your own development editor, such as Visual Studio Code. This is a little more complicated but can be made to work in consultation.

To start using Observable Desktop and you don’t already have one, you will need a free Observable account. Go to the Observable Desktop Guide to learn how to do this and also read through the guide for information about editing.

💡 Tip: When you create your Observable account you will receive a verification email — check your spam folder if it doesn’t arrive within a minute or two. Once verified, make sure you sign in to Observable Desktop using the same account (look for the sign-in prompt when you first open the app).

Adding an Anthropic → Claude API Key to Activate LLM Assistance

The AI assistant in Observable Desktop is powered by Claude (made by Anthropic). To use it you need to set up a separate pay-as-you-go Claude API account — this is different from a Claude.ai subscription. You are charged only for what you use (based on the amount of text sent back and forth), so there is no ongoing fee.

Step 1 — Create a Claude Platform account and add credit

Go to the Claude Platform and sign up. Once logged in, navigate to Billing and add some credit. The minimum top-up is $5 (plus any applicable tax — the exact total will depend on your location). I did this in August '24 and still had $1.82 credit the following February. Even with fairly regular use, it goes a long way.

Step 2 — Generate an API key

In the Claude Platform, go to API Keys (in the left-hand menu) and click Create Key. Give it a name (anything will do), then copy the key — you won’t be able to see it again after you close that screen.

Step 3 — Add the key to Observable Desktop

Open Observable Desktop, then in the menu bar go to:

Help  →  AI Settings

Paste your API key into the field provided and click Save. The AI assistant (which did help construct this guide!) will now be active in your notebooks.

💡 Tip: After you have added your API Key you will see Reset Anthropic API Key under Help, rather then API Settings.