page navigation

Author: mbostock

public/style.css

@@ -7,6 +7,7 @@
   --theme-background-color: rgb(var(--theme-background-rgb));
   --theme-background-color-alt: rgba(var(--theme-foreground-rgb), 0.05);
   --theme-foreground-color: rgb(var(--theme-foreground-rgb));
+  --theme-foreground-focus: #20bbfc;
   --syntax-comment: #828282;
   --syntax-diff: #24292e;
   --syntax-diff-bg: #ffffff;
@@ -32,14 +33,81 @@ html {
   -moz-osx-font-smoothing: grayscale;
   background: var(--theme-background-color);
   color: var(--theme-foreground-color);
-  margin: 2rem 1rem;
 }
 
 body {
-  margin: auto;
+  margin: 0;
+}
+
+main {
+  margin: 2rem auto;
   max-width: 1152px;
 }
 
+#observablehq-center {
+  margin: 1rem;
+}
+
+#observablehq-sidebar {
+  display: none;
+  position: fixed;
+  background: var(--theme-background-color-alt);
+  color: var(--theme-foreground-color);
+  font: 14px var(--sans-serif);
+  font-weight: 600;
+  width: 240px;
+  z-index: 1;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  padding: 1rem;
+}
+
+#observablehq-sidebar ol {
+  margin: 0;
+  padding: 0;
+}
+
+#observablehq-sidebar ol li {
+  display: block;
+  margin: 0;
+}
+
+.observablehq-link a {
+  display: block;
+  padding: 0.5rem 1rem;
+}
+
+.observablehq-link a:hover {
+  background: var(--theme-background-color);
+}
+
+.observablehq-link a[href] {
+  color: inherit;
+}
+
+.observablehq-link-active::before {
+  position: absolute;
+  content: "";
+  height: 2rem;
+  left: 0;
+  width: 3px;
+  background: var(--theme-foreground-focus);
+}
+
+.observablehq-link-active a[href] {
+  color: var(--theme-foreground-focus);
+}
+
+@media (min-width: 1200px) {
+  #observablehq-sidebar {
+    display: initial;
+  }
+  #observablehq-center {
+    padding-left: calc(240px + 2rem);
+  }
+}
+
 h1,
 h2,
 h3,
@@ -87,7 +155,9 @@ h6 code {
   font-size: 90%;
 }
 
-pre, code, tt {
+pre,
+code,
+tt {
   font-family: var(--monospace);
   font-size: 14px;
   line-height: 1.5;
@@ -121,8 +191,7 @@ blockquote {
   margin: 1rem 1.5rem;
 }
 
-ul
-ol {
+ul ol {
   padding-left: 28px;
 }
 
@@ -201,7 +270,8 @@ td {
   padding: 3px 6.5px 3px 0;
 }
 
-th:last-child, td:last-child {
+th:last-child,
+td:last-child {
   padding-right: 0;
 }
 

src/markdown.ts

@@ -13,6 +13,7 @@ interface ParseContext {
 }
 
 export interface ParseResult {
+  title: string | null;
   html: string;
   js: string;
   data: {[key: string]: any} | null;
@@ -198,11 +199,29 @@ export function parseMarkdown(source: string): ParseResult {
   const context: ParseContext = {id: 0, js: "", files: []};
   const tokens = md.parse(parts.content, context);
   const html = md.renderer.render(tokens, md.options, context);
-  return {html, js: context.js, data: isEmpty(parts.data) ? null : parts.data, files: context.files};
+  return {
+    html,
+    js: context.js,
+    data: isEmpty(parts.data) ? null : parts.data,
+    title: parts.data?.title ?? findTitle(tokens) ?? null,
+    files: context.files
+  };
 }
 
 // TODO Use gray-matter’s parts.isEmpty, but only when it’s accurate.
 function isEmpty(object) {
   for (const key in object) return false;
   return true;
 }
+
+// TODO Make this smarter.
+function findTitle(tokens: ReturnType<MarkdownIt["parse"]>): string | undefined {
+  for (const [i, token] of tokens.entries()) {
+    if (token.type === "heading_open" && token.tag === "h1") {
+      const next = tokens[i + 1];
+      if (next?.type === "inline" && next.children?.[0]?.type === "text") {
+        return next.content;
+      }
+    }
+  }
+}

src/preview.ts

@@ -1,5 +1,5 @@
 import {watch, type FSWatcher} from "node:fs";
-import {readFile, stat} from "node:fs/promises";
+import {readFile, readdir, stat} from "node:fs/promises";
 import type {IncomingMessage, RequestListener} from "node:http";
 import {createServer} from "node:http";
 import {basename, dirname, extname, join, normalize} from "node:path";
@@ -9,7 +9,8 @@ import send from "send";
 import {WebSocketServer, type WebSocket} from "ws";
 import {HttpError, isHttpError, isNodeError} from "./error.js";
 import {computeHash} from "./hash.js";
-import {renderPreview} from "./render.js";
+import {type ParseResult, parseMarkdown} from "./markdown.js";
+import {type RenderOptions, renderPreview} from "./render.js";
 
 const DEFAULT_ROOT = "docs";
 
@@ -18,9 +19,9 @@ const publicRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "public")
 class Server {
   private _server: ReturnType<typeof createServer>;
   private _socketServer: WebSocketServer;
-  private readonly port: number;
-  private readonly hostname: string;
-  private readonly root: string;
+  readonly port: number;
+  readonly hostname: string;
+  readonly root: string;
 
   constructor({port, hostname, root}: CommandContext) {
     this.port = port;
@@ -33,9 +34,9 @@ class Server {
     this._socketServer.on("connection", this._handleConnection);
   }
 
-  start() {
-    this._server.listen(this.port, this.hostname, () => {
-      console.log(`Server running at http://${this.hostname}:${this.port}/`);
+  async start() {
+    return new Promise<void>((resolve) => {
+      this._server.listen(this.port, this.hostname, resolve);
     });
   }
 
@@ -75,7 +76,8 @@ class Server {
         // Otherwise, serve the corresponding Markdown file, if it exists.
         // Anything else should 404; static files should be matched above.
         try {
-          res.end(renderPreview(await readFile(path + ".md", "utf-8")).html);
+          const pages = await this._readPages(); // TODO cache
+          res.end(renderPreview(await readFile(path + ".md", "utf-8"), {path: pathname, pages}).html);
         } catch (error) {
           if (!isNodeError(error) || error.code !== "ENOENT") throw error; // internal error
           throw new HttpError("Not found", 404);
@@ -89,6 +91,24 @@ class Server {
     }
   };
 
+  async _readPages() {
+    const pages: RenderOptions["pages"] = [];
+    for (const file of await readdir(this.root)) {
+      if (extname(file) !== ".md") continue;
+      let parsed: ParseResult;
+      try {
+        parsed = parseMarkdown(await readFile(join(this.root, file), "utf-8"));
+      } catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT") throw error; // internal error
+        continue;
+      }
+      const page = {path: `/${basename(file, ".md")}`, name: parsed.title ?? "Untitled"};
+      if (page.path === "/index") pages.unshift(page);
+      else pages.push(page);
+    }
+    return pages;
+  }
+
   _handleConnection = (socket: WebSocket, req: IncomingMessage) => {
     if (req.url === "/_observablehq") {
       handleWatch(socket, this.root);
@@ -190,5 +210,7 @@ function makeCommandContext(): CommandContext {
 
 await (async function () {
   const context = makeCommandContext();
-  new Server(context).start();
+  const server = new Server(context);
+  await server.start();
+  console.log(`Server running at http://${server.hostname}:${server.port}/`);
 })();

src/render.ts

@@ -7,21 +7,26 @@ export interface Render {
   files: {name: string; mimeType: string}[];
 }
 
-export function renderPreview(source: string): Render {
+export interface RenderOptions {
+  path?: string;
+  pages?: {path: string; name: string}[];
+}
+
+export function renderPreview(source: string, options: RenderOptions = {}): Render {
   const parseResult = parseMarkdown(source);
-  return {html: render(parseResult, {preview: true, hash: computeHash(source)}), files: parseResult.files};
+  return {html: render(parseResult, {...options, preview: true, hash: computeHash(source)}), files: parseResult.files};
 }
 
-export function renderServerless(source: string): Render {
+export function renderServerless(source: string, options: RenderOptions = {}): Render {
   const parseResult = parseMarkdown(source);
-  return {html: render(parseResult), files: parseResult.files};
+  return {html: render(parseResult, options), files: parseResult.files};
 }
 
-type RenderOptions =
-  | {preview?: false; hash?: never} // serverless mode
-  | {preview: true; hash: string}; // preview mode
+type RenderInternalOptions =
+  | {preview?: false; hash?: never} // serverless
+  | {preview: true; hash: string}; // preview
 
-function render(parseResult: ParseResult, {preview, hash}: RenderOptions = {}): string {
+function render(parseResult: ParseResult, {path, pages, preview, hash}: RenderOptions & RenderInternalOptions): string {
   return `<!DOCTYPE html>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
@@ -40,7 +45,38 @@ ${JSON.stringify(parseResult.data)}
 </script>`
       : ""
   }
+${
+  pages
+    ? `<nav id="observablehq-sidebar">
+  <ol>${pages
+    ?.map(
+      (p) => `
+    <li class="observablehq-link${p.path === path ? " observablehq-link-active" : ""}"><a href="${escapeDoubleQuoted(
+      p.path
+    )}">${escapeData(p.name)}</a></li>`
+    )
+    .join("")}
+  </ol>
+</nav>
+`
+    : ""
+}<div id="observablehq-center">
 <main>
-${parseResult.html}
-</main>`;
+${parseResult.html}</main>
+</div>
+`;
+}
+
+// TODO Adopt Hypertext Literal?
+function escapeDoubleQuoted(value): string {
+  return `${value}`.replace(/["&]/g, entity);
+}
+
+// TODO Adopt Hypertext Literal?
+function escapeData(value: string): string {
+  return `${value}`.replace(/[<&]/g, entity);
+}
+
+function entity(character) {
+  return `&#${character.charCodeAt(0).toString()};`;
 }

test/output/block-expression.json

@@ -1,4 +1,5 @@
 {
   "data": null,
+  "title": null,
   "files": []
 }

test/output/dollar-expression.json

@@ -1,4 +1,5 @@
 {
   "data": null,
+  "title": null,
   "files": []
 }

test/output/double-quote-expression.json

@@ -1,4 +1,5 @@
 {
   "data": null,
+  "title": null,
   "files": []
 }

test/output/embedded-expression.json

@@ -1,4 +1,5 @@
 {
   "data": null,
+  "title": "Embedded expression",
   "files": []
 }

test/output/escaped-expression.json

@@ -1,4 +1,5 @@
 {
   "data": null,
+  "title": null,
   "files": []
 }

test/output/fenced-code.json

@@ -1,4 +1,5 @@
 {
   "data": null,
+  "title": "Fenced code",
   "files": []
 }