head, header and footer can be specified as a function

that receives the page’s meta data (path, title and unrestricted front matter), and returns an HTML fragment (string).

closes #56
partially addresses #1036

Author: Fil

docs/config.md

@@ -162,6 +162,8 @@ An HTML fragment to add to the header. Defaults to the empty string.
 
 An HTML fragment to add to the footer. Defaults to “Built with Observable.”
 
+head, header and footer can be specified as strings, or as functions that receive the page’s meta data (path, title and front matter values) as the first argument, and return a string.
+
 ## scripts
 
 Additional scripts to add to the head, such as for analytics. Unlike the **head** option, this allows you to reference a local script in the source root.

src/config.ts

@@ -9,6 +9,7 @@ import type MarkdownIt from "markdown-it";
 import {LoaderResolver} from "./dataloader.js";
 import {visitMarkdownFiles} from "./files.js";
 import {formatIsoDate, formatLocaleDate} from "./format.js";
+import type {FrontMatter} from "./frontMatter.js";
 import {createMarkdownIt, parseMarkdownMetadata} from "./markdown.js";
 import {isAssetPath, parseRelativeUrl, resolvePath} from "./path.js";
 import {resolveTheme} from "./theme.js";
@@ -40,6 +41,11 @@ export interface Script {
   type: string | null;
 }
 
+/**
+ * A function that generates a page fragment such as head, header or footer.
+ */
+type PageFragmentFunction = (meta: FrontMatter & {title: string | null; path: string}) => string;
+
 export interface Config {
   root: string; // defaults to docs
   output: string; // defaults to dist
@@ -49,9 +55,9 @@ export interface Config {
   pages: (Page | Section<Page>)[];
   pager: boolean; // defaults to true
   scripts: Script[]; // defaults to empty array
-  head: string | null; // defaults to null
-  header: string | null; // defaults to null
-  footer: string | null; // defaults to “Built with Observable on [date].”
+  head: string | PageFragmentFunction | null; // defaults to null
+  header: string | PageFragmentFunction | null; // defaults to null
+  footer: string | PageFragmentFunction | null; // defaults to “Built with Observable on [date].”
   toc: TableOfContents;
   style: null | Style; // defaults to {theme: ["light", "dark"]}
   deploy: null | {workspace: string; project: string};
@@ -161,9 +167,9 @@ export function normalizeConfig(spec: any = {}, defaultRoot = "docs", watchPath?
   if (sidebar !== undefined) sidebar = Boolean(sidebar);
   pager = Boolean(pager);
   scripts = Array.from(scripts, normalizeScript);
-  head = stringOrNull(head);
-  header = stringOrNull(header);
-  footer = stringOrNull(footer);
+  head = pageFragment(head);
+  header = pageFragment(header);
+  footer = pageFragment(footer);
   toc = normalizeToc(toc);
   deploy = deploy ? {workspace: String(deploy.workspace).replace(/^@+/, ""), project: String(deploy.project)} : null;
   search = Boolean(search);
@@ -281,6 +287,10 @@ export function mergeStyle(
     : {theme};
 }
 
+function pageFragment(spec: unknown) {
+  return typeof spec === "function" ? spec : stringOrNull(spec);
+}
+
 export function stringOrNull(spec: unknown): string | null {
   return spec == null || spec === false ? null : String(spec);
 }

src/frontMatter.ts

@@ -15,6 +15,7 @@ export interface FrontMatter {
   draft?: boolean;
   sidebar?: boolean;
   sql?: {[key: string]: string};
+  [key: string]: any;
 }
 
 export function readFrontMatter(input: string): {content: string; data: FrontMatter} {
@@ -33,7 +34,7 @@ export function readFrontMatter(input: string): {content: string; data: FrontMat
 export function normalizeFrontMatter(spec: any = {}): FrontMatter {
   const frontMatter: FrontMatter = {};
   if (spec == null || typeof spec !== "object") return frontMatter;
-  const {title, sidebar, toc, index, keywords, draft, sql, head, header, footer, style, theme} = spec;
+  const {title, sidebar, toc, index, keywords, draft, sql, head, header, footer, style, theme, ...rest} = spec;
   if (title !== undefined) frontMatter.title = stringOrNull(title);
   if (sidebar !== undefined) frontMatter.sidebar = Boolean(sidebar);
   if (toc !== undefined) frontMatter.toc = normalizeToc(toc);
@@ -46,7 +47,7 @@ export function normalizeFrontMatter(spec: any = {}): FrontMatter {
   if (footer !== undefined) frontMatter.footer = stringOrNull(footer);
   if (style !== undefined) frontMatter.style = stringOrNull(style);
   if (theme !== undefined) frontMatter.theme = normalizeTheme(theme);
-  return frontMatter;
+  return {...frontMatter, ...rest};
 }
 
 function normalizeToc(spec: unknown): {show?: boolean; label?: string} {

src/markdown.ts

@@ -332,13 +332,14 @@ export function parseMarkdown(input: string, options: ParseOptions): MarkdownPag
   const context: ParseContext = {code, startLine: 0, currentLine: 0, path};
   const tokens = md.parse(content, context);
   const body = md.renderer.render(tokens, md.options, context); // Note: mutates code!
+  const title = data.title !== undefined ? data.title : findTitle(tokens);
   return {
-    head: getHtml("head", data, options),
-    header: getHtml("header", data, options),
+    head: getHtml("head", data, title, options),
+    header: getHtml("header", data, title, options),
     body,
-    footer: getHtml("footer", data, options),
+    footer: getHtml("footer", data, title, options),
     data,
-    title: data.title !== undefined ? data.title : findTitle(tokens),
+    title,
     style: getStyle(data, options),
     code
   };
@@ -360,12 +361,15 @@ export function parseMarkdownMetadata(input: string, options: ParseOptions): Pic
 function getHtml(
   key: "head" | "header" | "footer",
   data: FrontMatter,
+  title: string | null,
   {path, [key]: defaultValue}: ParseOptions
 ): string | null {
   return data[key] !== undefined
     ? data[key]
       ? String(data[key])
       : null
+    : typeof defaultValue === "function"
+    ? defaultValue({...data, path, title})
     : defaultValue != null
     ? rewriteHtmlPaths(defaultValue, path)
     : null;

test/frontMatter-test.ts

@@ -84,7 +84,7 @@ describe("normalizeFrontMatter(spec)", () => {
     assert.deepStrictEqual(normalizeFrontMatter({sql: {foo: []}}), {sql: {foo: ""}});
     assert.deepStrictEqual(normalizeFrontMatter({sql: {foo: {toString: () => "bar"}}}), {sql: {foo: "bar"}});
   });
-  it("ignores unknown properties", () => {
-    assert.deepStrictEqual(normalizeFrontMatter({foo: 42}), {});
+  it("passes unknown properties unchanged", () => {
+    assert.deepStrictEqual(normalizeFrontMatter({foo: 42}), {foo: 42});
   });
 });

test/input/build/fragments/index.md

@@ -0,0 +1,7 @@
+---
+hello: front-matter
+title: Testing fragment functions
+meta: ["very", "much"]
+---
+
+Contents.

test/input/build/fragments/observablehq.config.js

@@ -0,0 +1,5 @@
+export default {
+  head: (data) => JSON.stringify({hello: "head", data}),
+  header: (data) => JSON.stringify({hello: "header", data}),
+  footer: (data) => JSON.stringify({hello: "footer", data}),
+};

test/output/build/fragments/index.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
+<title>Testing fragment functions</title>
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="preload" as="style" href="https://fonts.googleapis.com/css2?family=Source+Serif+Pro:ital,wght@0,400;0,600;0,700;1,400;1,600;1,700&amp;display=swap" crossorigin>
+<link rel="preload" as="style" href="./_observablehq/theme-air,near-midnight.css">
+<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css2?family=Source+Serif+Pro:ital,wght@0,400;0,600;0,700;1,400;1,600;1,700&amp;display=swap" crossorigin>
+<link rel="stylesheet" type="text/css" href="./_observablehq/theme-air,near-midnight.css">
+<link rel="modulepreload" href="./_observablehq/client.js">
+<link rel="modulepreload" href="./_observablehq/runtime.js">
+<link rel="modulepreload" href="./_observablehq/stdlib.js">
+{"hello":"head","data":{"title":"Testing fragment functions","hello":"front-matter","meta":["very","much"],"path":"/index"}}
+<script type="module">
+
+import "./_observablehq/client.js";
+
+</script>
+<aside id="observablehq-toc" data-selector="h1:not(:first-of-type), h2:first-child, :not(h1) + h2">
+<nav>
+</nav>
+</aside>
+<div id="observablehq-center">
+<header id="observablehq-header">
+{"hello":"header","data":{"title":"Testing fragment functions","hello":"front-matter","meta":["very","much"],"path":"/index"}}
+</header>
+<main id="observablehq-main" class="observablehq">
+<p>Contents.</p>
+</main>
+<footer id="observablehq-footer">
+<div>{"hello":"footer","data":{"title":"Testing fragment functions","hello":"front-matter","meta":["very","much"],"path":"/index"}}</div>
+</footer>
+</div>