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 desktop app is a notebook editor that creates, edits and saves, basically, HTML files. (These files have .html as their extension). You will be editing these files inside folders that are organized to use the Observable Notebook Kit. We set all this up in order to be able turn your notebooks into publishable web sites, locally, at first.

  1. In whatever way is most comfortable for you (and best organized) create a folder called something appropriate like: ObservableNotebooks.
  2. Inside this folder make another folder called docs. This is where you will create and store your notebook files.
  3. Open Observable Desktop and then edit the Untitled default document that appears. Edit the title and create a few more MarkDown (md) cells with some (placeholder) text in them.
  4. Select File —> Save As... to save what you’ve done, with a name based on the title you chose, inside the docs folder of your project folder.
  5. Now use your Terminal program and its Command Line Interface (CLI) to navigate to your ObservableNotebooks project folder. (If you haven’t done this before, we’ll do it Together First In Workshop and/or ask questions.)
  6. And, if you’ve never done so before, you will need to install node.js and a Package Manager called npm (Node Package Manager). Go to step 8 if you already have npm installed, otherwise:
  7. Download the installer for node.js that is best for your computer. If you have a Mac download from here. Verify at the terminal with (on separate lines):
    node -v
    npm -v
    (which will show the installed versions of these packages).
  8. Next, at the Terminal prompt type:
    npm add @observablehq/notebook-kit
  9. Hopefully you have a plain text editor that you like to use. Find and edit the file package.json (which has been created by the previous step) so that it looks like this (it’s the scripts part that needs adding):
{
  "dependencies": {
    "@observablehq/notebook-kit": "^1.5.0"
  },
  "scripts": {
    "preview": "notebooks preview --root docs --template docs/nochrome.tmpl",
    "build": "notebooks build --root docs --template docs/nochrome.tmpl --out ../dist -- docs/*.html"
  }
}
  1. This file refers to another, a template file, called nochrome.tmpl so now you also need to create this file inside your docs folder. Make a new plain text file using you editor and save it in the docs folder. Make sure the file name has that .tmpl extension. Its contents should look like this:
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <style type="text/css">
      @import url("observable:styles/index.css");
      * {
        margin-top:0 !important;
      }
      html {
        background-color: white;
        margin:0;
        padding:2vw; /* change this to 0 to override default */
        border:0;
      }
      body {
        max-width: none;
        margin:0;
        padding:0;
        border:0;
      }
    </style>
  </head>
  <body>
    <main></main>
  </body>
</html>
  1. Finally (for now) in your terminal, type: npm run preview. Then type h and hit return. Read and explore what is displayed.

Note

Even once you’ve done all the above and ironed out any bugs, you may still be surprised when you are trying to preview (by running the script and then hitting o+return to ‘Open’ your notebook as a site).

You may get a file not found error because the site that Observable builds for you expects to find a notebook HTML file named index.html as the default entrance to the website it has just built. An immediate fix is to type at the end of whatever is in you browser’s URL box, add the file name of your notebook: <whateverucalledit>.html. Alternatively, you could rename one of your notebook files as index.html.