Table of Contents

docs/.observablehq/config.ts

@@ -28,5 +28,8 @@ export default {
       ]
     },
     {name: "Contributing", path: "/contributing"}
-  ]
+  ],
+  toc: {
+    label: "Contents"
+  }
 };

docs/getting-started.md

@@ -1,3 +1,8 @@
+---
+toc:
+  show: true
+---
+
 # Getting started
 
 The Observable CLI is a Node.js application and is published to npm as [`@observablehq/cli`](https://www.npmjs.com/package/@observablehq/cli). As the name suggests, the CLI lives on the command line; the instructions below are intended to run in your [terminal](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac). You’ll need to install [Node.js 18 or later](https://nodejs.org/) before you can install the CLI.
@@ -88,3 +93,41 @@ observable build
 Creates `dist`.
 
 You can use `npx http-server dist` to preview your built site.
+
+## Configuration
+
+Add a `config.js` or `config.ts` file under the `.observablehq` directory. Example config:
+
+```
+{
+  title: "Hello World",
+  pages: [
+    {name: "Getting started", path: "/getting-started"},
+    {
+      name: "JavaScript",
+      pages: [
+        {name: "Reactivity", path: "/javascript/reactivity"},
+        {name: "Display", path: "/javascript/display"},
+      ]
+    }
+  ],
+  toc: {
+    label: "Contents"
+    show: true
+  }
+}
+```
+
+You can configure:
+
+### `title`
+
+Customize the title on the left sidebar.
+
+### `pages`
+
+A page has a name and path. The page path corresponds to the path of the `.md` file from your root directory. For example, if `docs` is your root directory, the `docs/javascript.md` file corresponds to the `/javascript` path
+
+### `table of contents on a page`
+
+`label` is the name of the TOC (table of contents) section. Setting `show` to `true` renders the TOC globally with `h2` tags.

docs/loaders.md

@@ -1,3 +1,8 @@
+---
+toc:
+  show: true
+---
+
 # Data loaders
 
 **Data loaders** generate files — typically static snapshots of data — at build time. For example, a data loader might query a database and output a CSV or Parquet file, or server-side render a chart and output a PNG image.
@@ -28,7 +33,9 @@ And that’s it! The CLI automatically runs the data loader. (More details below
 Now we can display the earthquakes in a map:
 
 ```js
-const world = await fetch("https://cdn.jsdelivr.net/npm/world-atlas@1/world/110m.json").then((response) => response.json());
+const world = await fetch("https://cdn.jsdelivr.net/npm/world-atlas@1/world/110m.json").then((response) =>
+  response.json()
+);
 const land = topojson.feature(world, world.objects.land);
 ```
 
@@ -44,7 +51,7 @@ Plot.plot({
     Plot.geo(land, {stroke: "var(--theme-foreground-faint)"}),
     Plot.dot(quakes, {x: "longitude", y: "latitude", r: "magnitude", stroke: "#f43f5e"})
   ]
-})
+});
 ```
 
 Here are some more details on data loaders.
@@ -53,21 +60,21 @@ Here are some more details on data loaders.
 
 Data loaders live in `docs` alongside your other source files. When a file is referenced from JavaScript, either via [`FileAttachment`](./javascript/files) or [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), if the file does not exist, the CLI will look for a file of the same name with a double extension to see if there is a corresponding data loader. The following second extensions are checked, in order, with the corresponding language and interpreter:
 
-* `.js` - JavaScript (`node`)
-* `.ts` - TypeScript (`tsx`)
-* `.py` - Python (`python3`)
-* `.R` - R (`Rscript`)
-* `.sh` - shell script (`sh`)
-* `.exe` - arbitrary executable
+- `.js` - JavaScript (`node`)
+- `.ts` - TypeScript (`tsx`)
+- `.py` - Python (`python3`)
+- `.R` - R (`Rscript`)
+- `.sh` - shell script (`sh`)
+- `.exe` - arbitrary executable
 
 For example, for the file `earthquakes.csv`, the following data loaders are considered:
 
-* `earthquakes.csv.js`
-* `earthquakes.csv.ts`
-* `earthquakes.csv.py`
-* `earthquakes.csv.R`
-* `earthquakes.csv.sh`
-* `earthquakes.csv.exe`
+- `earthquakes.csv.js`
+- `earthquakes.csv.ts`
+- `earthquakes.csv.py`
+- `earthquakes.csv.R`
+- `earthquakes.csv.sh`
+- `earthquakes.csv.exe`
 
 If you use `.py` or `.R`, the corresponding interpreter (`python3` or `Rscript`, respectively) must be installed and available on your `$PATH`. Any additional modules, packages, libraries, _etc._, must also be installed before you can use them.
 
@@ -77,7 +84,7 @@ Whereas `.js`, `.ts`, `.py`, `.R`, and `.sh` data loaders are run via interprete
 chmod +x docs/earthquakes.csv.exe
 ```
 
-While a `.exe` data loader may be any binary executable (_e.g.,_ compiled from C), it is often convenient to specify another interpreter using a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)). For example, to write a data loader in Julia:
+While a `.exe` data loader may be any binary executable (_e.g.,_ compiled from C), it is often convenient to specify another interpreter using a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). For example, to write a data loader in Julia:
 
 ```julia
 #!/usr/bin/env julia
@@ -89,7 +96,7 @@ If multiple requests are made concurrently for the same data loader, the data lo
 
 ## Output
 
-Data loaders must output to [stdout](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)). The first extension (such as `.csv`) is not considered by the CLI; the data loader is solely responsible for producing the expected output (such as CSV). If you wish to log additional information from within a data loader, be sure to log to stderr, say by using [`console.warn`](https://developer.mozilla.org/en-US/docs/Web/API/console/warn); otherwise the logs will be included in the output file and sent to the client.
+Data loaders must output to [stdout](<https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)>). The first extension (such as `.csv`) is not considered by the CLI; the data loader is solely responsible for producing the expected output (such as CSV). If you wish to log additional information from within a data loader, be sure to log to stderr, say by using [`console.warn`](https://developer.mozilla.org/en-US/docs/Web/API/console/warn); otherwise the logs will be included in the output file and sent to the client.
 
 ## Caching
 

public/client.js

@@ -223,7 +223,7 @@ export function open({hash, eval: compile} = {}) {
         });
         break;
       case "update": {
-        const root = document.querySelector("main");
+        const root = document.querySelector("#observablehq-cells");
         if (message.previousHash !== hash) {
           console.log("contents out of sync");
           location.reload();
@@ -352,3 +352,144 @@ function enableCopyButtons() {
 async function copy({currentTarget}) {
   await navigator.clipboard.writeText(currentTarget.parentElement.textContent.trimEnd());
 }
+
+class Node {
+  constructor(value) {
+    this.value = value;
+    this.previous = null;
+    this.next = null;
+  }
+}
+
+class DoublyLinkedList {
+  constructor() {
+    this.first = null;
+    this.last = null;
+    this.size = 0;
+  }
+
+  insert(value) {
+    this.size++;
+    let newNode = new Node(value);
+    if (this.last) {
+      this.last.next = newNode;
+      newNode.previous = this.last;
+      this.last = newNode;
+      return newNode;
+    }
+    this.first = this.last = newNode;
+    return newNode;
+  }
+
+  find(hash) {
+    let node = this.first;
+    while (node) {
+      if (node.value.firstElementChild.getAttribute("href") === hash) {
+        return node;
+      }
+      node = node.next;
+    }
+  }
+}
+
+const toc = document.querySelector("#observablehq-toc");
+const secondaryActiveLinkClass = "observablehq-secondary-link-active";
+let headingNodes = document.querySelectorAll("h2");
+let headings = new DoublyLinkedList();
+headingNodes.forEach((headingNode) => headings.insert(headingNode));
+
+if (toc) {
+  highlightSection();
+}
+
+function highlightSection() {
+  function getHeaderPositionY(heading) {
+    return heading && heading.getBoundingClientRect().y + window.scrollY;
+  }
+
+  function isTopOfPage() {
+    return window.scrollY === 0;
+  }
+
+  function isBottomOfPage() {
+    return window.scrollY + window.innerHeight >= document.body.scrollHeight;
+  }
+
+  function highlightSection(hash) {
+    return document.querySelector(`nav ol li a[href="${hash}"]`).parentElement.classList.add(secondaryActiveLinkClass);
+  }
+
+  function unhighlightSection(hash) {
+    return document
+      .querySelector(`nav ol li a[href="${hash}"]`)
+      .parentElement.classList.remove(secondaryActiveLinkClass);
+  }
+
+  function headingInView(heading) {
+    if (!heading) return false;
+    const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+    const bounding = heading.getBoundingClientRect();
+    return viewportHeight - bounding.top > 0 && bounding.left > 0;
+  }
+
+  let currHeading;
+  let debounce;
+  function handleScroll() {
+    if (debounce) return;
+    if (isTopOfPage()) {
+      // top heading in view
+      if (headingInView(headings.first.value)) {
+        if (currHeading) unhighlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+        currHeading = headings.first;
+        highlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+      }
+    } else if (isBottomOfPage()) {
+      // reached the bottom
+      if (currHeading) unhighlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+      if (headings.last.value) {
+        currHeading = headings.last;
+        highlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+      }
+    } else {
+      if (!currHeading) {
+        if (headingInView(headings.first.value)) {
+          // first section is not at the top of the page
+          // it hasn't been set yet, setting now
+          currHeading = headings.first;
+          highlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+        }
+      } else {
+        if (currHeading.next && window.scrollY > getHeaderPositionY(currHeading.next.value)) {
+          // scrolling down
+          if (currHeading) unhighlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+          highlightSection(currHeading.next.value.firstElementChild.getAttribute("href"));
+          currHeading = currHeading.next;
+        } else {
+          // scrolling up
+          if (currHeading !== headings.first && window.scrollY < getHeaderPositionY(currHeading.value)) {
+            if (currHeading) unhighlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+            highlightSection(currHeading.previous.value.firstElementChild.getAttribute("href"));
+            currHeading = currHeading.previous;
+          } else if (!headingInView(currHeading.value)) {
+            unhighlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+          }
+        }
+      }
+    }
+  }
+  document.addEventListener("scroll", handleScroll);
+
+  function highlightHash() {
+    if (location.hash) {
+      debounce = true;
+      if (currHeading) unhighlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+      currHeading = headings.find(location.hash);
+      highlightSection(currHeading.value.firstElementChild.getAttribute("href"));
+      setTimeout(() => (debounce = false), 1000);
+    }
+  }
+
+  document.addEventListener("DOMContentLoaded", highlightHash);
+
+  window.addEventListener("hashchange", highlightHash);
+}