Setting up
Observable Notebook Kit

in order to develop notebooks into websites locally

Create your First Project Folder and Set Up the Notebook Kit

The Observable Desktop app is a notebook editor that creates, edits, and saves HTML files. (These files have .html as their extension but have a special format.) Instructions for setting up the desktop app are another linked notebook of this site.

You will be editing these files inside folders that are organized to use the Observable Notebook Kit. Once set up, the Kit allows you to turn your notebooks into a publishable website that you can view locally at first, and then share publicly.

Before you begin: get a plain text editor

For some of the steps below you will need a plain text editor — this is different from a word processor like Word. If you already have one you like, use it. Otherwise:

  • Mac: Download and install CotEditor — it’s free and simple.
  • PC: Download and install Notepad++ — also free and widely used.

Step-by-step setup

1. Create your project folder structure

In whatever way is most comfortable for you, create a folder called something like ObservableNotebooks. Inside it, create a subfolder called nbks — this is where your notebook files will live.

2. Install Node.js (skip to step 3 if you already have it)

You need a tool called Node.js installed on your computer. It comes with a companion tool called npm (Node Package Manager) that we’ll use in a moment.

Once installed, verify it worked by opening your Terminal (see step 3 below for how to open it) and typing these two commands, one at a time, hitting Return after each:

node -v
npm -v

Each should print a version number (e.g. v22.0.0). If you see numbers, you’re good.

3. Open your Terminal and navigate to your project folder

The Terminal is a text-based way to give your computer instructions. Don’t be intimidated — you only need a couple of commands.

  • Mac: Open Spotlight (⌘ Space), type Terminal, and press Return.
  • PC: Press the Windows key, type PowerShell, and press Return.

Once Terminal is open, you need to navigate into your ObservableNotebooks folder. The easiest way:

  1. Type cd (the letters c, d, and a space — don’t press Return yet).
  2. Drag your ObservableNotebooks folder from Finder/Explorer into the Terminal window. It will paste the full path for you.
  3. Now press Return.

You are now “inside” your project folder. All the following commands should be run from here.

4. Install the Observable Notebook Kit

In your Terminal, type:

npm add @observablehq/notebook-kit

This will create two things inside your ObservableNotebooks folder: a file called package.json and a folder called node_modules.

5. Edit package.json to add build scripts

Open package.json in your plain text editor (see above). It will already have a dependencies section written by the previous step — don’t change this line. You just need to add a scripts section. The entire file should look like this but may have a different version number. The version shown here (^2.1.5) may be out of date:

{
  "dependencies": {
    "@observablehq/notebook-kit": "^2.1.5"
  },
  "scripts": {
    "preview": "notebooks preview --root nbks",
    "build": "notebooks build --root nbks --out ../docs -- *.html"
  }
}

Note on the build script: The --out ../docs part puts the built website into a docs inside your project folder because its specification is relative to the root – your nbks folder – that you are specifying. nbks and docs will be at the same level inside your project folder.

Save the file.

6. Create your first notebook

Open the Observable Desktop app. An Untitled document will appear. Edit the title and add a few Markdown (md) cells with some text.

Then select File → Save As... and save the file as index.html inside your nbks folder.

Why index.html? This filename is special: it’s the page that loads automatically when someone visits the root of your website (e.g. yoursite.com/ rather than yoursite.com/something.html).

7. Launch the preview server

Back in your Terminal, type:

npm run preview

This starts a local web server so you can see your notebooks as a website in your browser. Once it’s running, type h and press Return to see a list of keyboard shortcuts and options — take a moment to read through them. … And then type o and Return to see what happens!