markdown-it plugins (#965)

Author: mbostock

docs/config.md

@@ -195,3 +195,16 @@ toc: false
 ## search
 
 Whether to enable [search](./search) on the project; defaults to false.
+
+## markdownIt
+
+A hook for registering additional [markdown-it](https://github.com/markdown-it/markdown-it) plugins. For example, to use [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote):
+
+```js
+import type MarkdownIt from "markdown-it";
+import MarkdownItFootnote from "markdown-it-footnote";
+
+export default {
+  markdownIt: (md: MarkdownIt) => md.use(MarkdownItFootnote);
+};
+```

src/config.ts

@@ -2,6 +2,7 @@ import op from "node:path";
 import {basename, dirname, join} from "node:path/posix";
 import {cwd} from "node:process";
 import {pathToFileURL} from "node:url";
+import type MarkdownIt from "markdown-it";
 import {visitMarkdownFiles} from "./files.js";
 import {formatIsoDate, formatLocaleDate} from "./format.js";
 import {parseMarkdown} from "./markdown.js";
@@ -50,6 +51,7 @@ export interface Config {
   style: null | Style; // defaults to {theme: ["light", "dark"]}
   deploy: null | {workspace: string; project: string};
   search: boolean; // default to false
+  markdownIt?: (md: MarkdownIt) => MarkdownIt;
 }
 
 export async function readConfig(configPath?: string, root?: string): Promise<Config> {
@@ -107,6 +109,7 @@ export async function normalizeConfig(spec: any = {}, defaultRoot = "docs"): Pro
       currentDate
     )}">${formatLocaleDate(currentDate)}</a>.`
   } = spec;
+  const {markdownIt} = spec;
   root = String(root);
   output = String(output);
   base = normalizeBase(base);
@@ -125,7 +128,25 @@ export async function normalizeConfig(spec: any = {}, defaultRoot = "docs"): Pro
   toc = normalizeToc(toc);
   deploy = deploy ? {workspace: String(deploy.workspace).replace(/^@+/, ""), project: String(deploy.project)} : null;
   search = Boolean(search);
-  return {root, output, base, title, sidebar, pages, pager, scripts, head, header, footer, toc, style, deploy, search};
+  if (markdownIt !== undefined && typeof markdownIt !== "function") throw new Error("markdownIt must be a function");
+  return {
+    root,
+    output,
+    base,
+    title,
+    sidebar,
+    pages,
+    pager,
+    scripts,
+    head,
+    header,
+    footer,
+    toc,
+    style,
+    deploy,
+    search,
+    markdownIt
+  };
 }
 
 function normalizeBase(base: any): string {

src/markdown.ts

@@ -272,16 +272,17 @@ function makeSoftbreakRenderer(baseRenderer: RenderRule): RenderRule {
 export interface ParseOptions {
   root: string;
   path: string;
+  markdownIt?: Config["markdownIt"];
   style?: Config["style"];
 }
 
 export async function parseMarkdown(
   sourcePath: string,
-  {root, path, style: configStyle}: ParseOptions
+  {root, path, markdownIt = (md) => md, style: configStyle}: ParseOptions
 ): Promise<MarkdownPage> {
   const source = await readFile(sourcePath, "utf-8");
   const parts = matter(source, {});
-  const md = MarkdownIt({html: true});
+  const md = markdownIt(MarkdownIt({html: true}));
   md.use(MarkdownItAnchor, {permalink: MarkdownItAnchor.permalink.headerLink({class: "observablehq-header-anchor"})});
   md.inline.ruler.push("placeholder", transformPlaceholderInline);
   md.core.ruler.before("linkify", "placeholder", transformPlaceholderCore);

src/preview.ts

@@ -282,7 +282,8 @@ function getWatchFiles(resolvers: Resolvers): Iterable<string> {
   return files;
 }
 
-function handleWatch(socket: WebSocket, req: IncomingMessage, {root, style}: Config) {
+function handleWatch(socket: WebSocket, req: IncomingMessage, config: Config) {
+  const {root} = config;
   let path: string | null = null;
   let hash: string | null = null;
   let html: string[] | null = null;
@@ -312,7 +313,7 @@ function handleWatch(socket: WebSocket, req: IncomingMessage, {root, style}: Con
         break;
       }
       case "change": {
-        const page = await parseMarkdown(join(root, path), {root, path, style});
+        const page = await parseMarkdown(join(root, path), {path, ...config});
         // delay to avoid a possibly-empty file
         if (!force && page.html === "") {
           if (!emptyTimeout) {
@@ -361,7 +362,7 @@ function handleWatch(socket: WebSocket, req: IncomingMessage, {root, style}: Con
     if (!(path = normalize(path)).startsWith("/")) throw new Error("Invalid path: " + initialPath);
     if (path.endsWith("/")) path += "index";
     path += ".md";
-    const page = await parseMarkdown(join(root, path), {root, path, style});
+    const page = await parseMarkdown(join(root, path), {path, ...config});
     const resolvers = await getResolvers(page, {root, path});
     if (resolvers.hash !== initialHash) return void send({type: "reload"});
     hash = resolvers.hash;

test/config-test.ts

@@ -30,7 +30,8 @@ describe("readConfig(undefined, root)", () => {
         workspace: "acme",
         project: "bi"
       },
-      search: false
+      search: false,
+      markdownIt: undefined
     });
   });
   it("returns the default config if no config file is found", async () => {
@@ -50,7 +51,8 @@ describe("readConfig(undefined, root)", () => {
       footer:
         'Built with <a href="https://observablehq.com/" target="_blank">Observable</a> on <a title="2024-01-11T01:02:03">Jan 11, 2024</a>.',
       deploy: null,
-      search: false
+      search: false,
+      markdownIt: undefined
     });
   });
 });