vowel 0.7.0-beta.0 → 0.7.1

package/plugins/export/index.js

@@ -0,0 +1,131 @@
+import { cp, readdir, stat } from "node:fs/promises"
+import { realpathSync } from "node:fs"
+import path from "node:path"
+import votive from "votive"
+import { systemDirectoryFor } from "../../systemPaths.js"
+
+/** @import * as Votive from "votive" */
+
+/**
+ * `vowel export <folder>`: build the site and copy it to a folder of
+ * your choosing - to upload anywhere, archive, or hand to someone. The
+ * same command a desktop "Export" button would run
+ * (`vowel --command export --payload '{"path": "…"}'`).
+ *
+ * It copies the output folder whole. If the output ever holds files it
+ * shouldn't, that is the output's problem to fix, not the export's.
+ *
+ * **Where it won't write**, checked before anything is built, on real
+ * paths so a symlink can't hide the answer:
+ * - inside the project: the next build would read the export as content,
+ *   and each export would nest inside the next
+ * - a folder that contains the project, or is it
+ * - vowel's own system folder (the output, the database, the cache)
+ * - a folder that isn't empty: nothing an export writes should mix with,
+ *   or silently replace, what's already there
+ *
+ * A destination that doesn't exist yet is created.
+ */
+
+/**
+ * `child` is `parent` or somewhere inside it.
+ * @param {string} child
+ * @param {string} parent
+ */
+function within(child, parent) {
+  const relative = path.relative(parent, child)
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
+}
+
+/**
+ * A path made real as far as it exists: the deepest existing ancestor
+ * through realpath (symlinks resolved, and on a case-insensitive disk
+ * its true case), then the segments that don't exist yet.
+ * @param {string} absolute
+ * @returns {string}
+ */
+function realAsFarAsItExists(absolute) {
+  try {
+    return realpathSync.native(absolute)
+  } catch {
+    const parent = path.dirname(absolute)
+    if (parent === absolute) return absolute
+    return path.join(realAsFarAsItExists(parent), path.basename(absolute))
+  }
+}
+
+/**
+ * Where an export may go, or why it may not, as a sentence. Checks the
+ * places only; whether the folder is empty is `checkEmpty`'s.
+ * @param {string} destination - as given; relative to the working directory
+ * @param {{ sourceFolder: string, targetFolder: string }} config
+ * @returns {{ path: string } | { refused: string }}
+ */
+function checkDestination(destination, config) {
+  if (typeof destination !== "string" || !destination.trim()) {
+    return { refused: "say where to export to, e.g. `vowel export ../my-site`" }
+  }
+  const real = realAsFarAsItExists(path.resolve(destination))
+  const source = realAsFarAsItExists(config.sourceFolder)
+  const system = realAsFarAsItExists(systemDirectoryFor(config.sourceFolder))
+  const output = realAsFarAsItExists(config.targetFolder)
+
+  if (within(real, source)) {
+    return { refused: `${destination} is inside the project (${source}); the next build would read the export as part of the site. Export somewhere outside it.` }
+  }
+  if (within(source, real)) {
+    return { refused: `${destination} contains the project (${source}). Export to a folder of its own.` }
+  }
+  if (within(real, system) || within(real, output) || within(output, real)) {
+    return { refused: `${destination} is where vowel keeps its own build (${system}). Export somewhere else.` }
+  }
+  return { path: real }
+}
+
+/**
+ * @param {string} folder - real, absolute
+ * @param {string} destination - as given, for the message
+ * @returns {Promise<string | undefined>} why it can't be used, if it can't
+ */
+async function checkEmpty(folder, destination) {
+  const info = await stat(folder).catch(() => undefined)
+  if (!info) return undefined
+  if (!info.isDirectory()) return `${destination} is a file, not a folder.`
+  const entries = await readdir(folder)
+  if (entries.length) return `${destination} isn't empty. Export to a new or empty folder.`
+  return undefined
+}
+
+/**
+ * @param {{ path?: string } | undefined} payload
+ * @param {{ config: Votive.VotiveConfig, notify: (message: object) => void }} context
+ */
+async function exportSite(payload, { config, notify }) {
+  const checked = checkDestination(payload?.path, config)
+  if ("refused" in checked) throw new Error(`export: ${checked.refused}`)
+  const notEmpty = await checkEmpty(checked.path, payload.path)
+  if (notEmpty) throw new Error(`export: ${notEmpty}`)
+
+  notify({ status: "progress", message: "Building..." })
+  // As deploy does: everything finished, deferred work (image
+  // derivatives, link previews) included, and the database closed.
+  const site = await votive({ ...config, verbose: false })
+  await (await site.build()).deferred
+  await site.close()
+
+  notify({ status: "progress", message: `Copying to ${checked.path}...` })
+  await cp(config.targetFolder, checked.path, { recursive: true })
+  const files = await readdir(checked.path, { recursive: true, withFileTypes: true })
+  const count = files.filter(entry => entry.isFile()).length
+  notify({ status: "done", message: `Exported ${count} files to ${checked.path}` })
+  return { exported: checked.path, files: count }
+}
+
+/** @type {Votive.VotivePlugin} */
+const vowelExportPlugin = {
+  name: "vowel-export",
+  commands: { export: exportSite }
+}
+
+export default vowelExportPlugin
+export { exportSite, checkDestination, within }

package/plugins/html/bundle/index.js

@@ -18761,9 +18761,10 @@ ${fallback_html}`;
 	    return { type: "blockquote", children: node.body.nodes.map(child => blockFrom$1(child, nodes)) }
 	  }
 	  if (node.type === "alert") {
+	    const title = node.title ? ` ${node.title}` : "";
 	    const marker = {
 	      type: "html",
-	      value: `[!${(node.variant || "note").toUpperCase()}]`
+	      value: `[!${(node.variant || "note").toUpperCase()}]${title}`
 	    };
 	    const body = node.body.nodes.map(child => blockFrom$1(child, nodes));
 	    return { type: "blockquote", children: [marker, ...body] }
@@ -18798,11 +18799,12 @@ ${fallback_html}`;
 	    rule: "-"
 	  });
 	  const heading = frontmatter.title ? `# ${frontmatter.title}\n\n` : "";
+	  const natural = frontmatter.natural || "";
 	  const properties = frontmatter.properties || {};
 	  const yaml = Object.keys(properties).length
 	    ? `---\n${stringify(properties)}---\n\n`
 	    : "";
-	  return yaml + heading + body
+	  return yaml + heading + natural + body
 	}
 
 	const divider = ($$anchor) => {
@@ -19533,9 +19535,11 @@ ${fallback_html}`;
 		// socket pushes, so it is read at save time rather than when the
 		// editor opened. Taking the frontmatter from the source rather than
 		// the rendered page is what lets a key that never renders survive a
-		// save. The title is the one key that isn't kept: it is written back
-		// as a `#` heading, never as `title:`, so a file whose title lived
-		// only in frontmatter gains a heading and loses the key.
+		// save. A title declared in the frontmatter (`h1.fm_title`) stays a
+		// `title:` key; one from a `#` heading is written back as one. The
+		// natural metadata - a date line, an image, a description and its
+		// rule, lifted out of the content when the page was built - goes back
+		// between the heading and the body.
 		async function save() {
 			const { path, markdown: text } = getSource();
 
@@ -19545,8 +19549,10 @@ ${fallback_html}`;
 				return;
 			}
 
-			const { title: ignoredTitle, ...properties } = splitFrontmatter(text).data;
-			const markdown = serialize($$props.session.doc, { title: $$props.frontmatter.title, properties });
+			const { title: sourceTitle, ...rest } = splitFrontmatter(text).data;
+			const properties = $$props.frontmatter.titleDeclared ? { title: sourceTitle, ...rest } : rest;
+			const title = $$props.frontmatter.titleDeclared ? null : $$props.frontmatter.title;
+			const markdown = serialize($$props.session.doc, { title, natural: $$props.frontmatter.natural, properties });
 
 			await writeSettings(path, markdown);
 			console.info("[vowel] saved %s", path);
@@ -19684,14 +19690,14 @@ ${fallback_html}`;
 	delegate(['click']);
 
 	const rampSettings = [
-	  { key: "heading-size", variable: "--font-size-delta", label: "Heading size", hint: "How much larger h1 is than body text", unit: "x", min: 0.25, max: 4, step: 0.05, default: 2 },
-	  { key: "heading-size-decay", variable: "--font-size-decay", label: "Size decay", hint: "Higher makes subheadings smaller", unit: "", min: 0.5, max: 6, step: 0.1, default: 3 },
-	  { key: "h1-letter-spacing", variable: "--letter-spacing-h1", label: "h1 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: -0.01 },
-	  { key: "h6-letter-spacing", variable: "--letter-spacing-h6", label: "h6 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: 0 },
-	  { key: "letter-spacing-decay", variable: "--letter-spacing-decay", label: "Spacing decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 },
-	  { key: "h1-weight", variable: "--font-weight-h1", label: "h1 weight", unit: "", min: 100, max: 900, step: 10, default: 800 },
-	  { key: "h6-weight", variable: "--font-weight-h6", label: "h6 weight", unit: "", min: 100, max: 900, step: 10, default: 600 },
-	  { key: "weight-decay", variable: "--font-weight-decay", label: "Weight decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 }
+	  { key: "heading-size", variable: "--fontsize-delta", label: "Heading size", hint: "How much larger h1 is than body text", unit: "x", min: 0.25, max: 4, step: 0.05, default: 2 },
+	  { key: "heading-size-decay", variable: "--fontsize-decay", label: "Size decay", hint: "Higher makes subheadings smaller", unit: "", min: 0.5, max: 6, step: 0.1, default: 3 },
+	  { key: "h1-letter-spacing", variable: "--letterspacing-h1", label: "h1 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: -0.01 },
+	  { key: "h6-letter-spacing", variable: "--letterspacing-h6", label: "h6 letter spacing", unit: "ch", min: -0.1, max: 0.1, step: 0.005, default: 0 },
+	  { key: "letter-spacing-decay", variable: "--letterspacing-decay", label: "Spacing decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 },
+	  { key: "h1-weight", variable: "--fontweight-h1", label: "h1 weight", unit: "", min: 100, max: 900, step: 10, default: 800 },
+	  { key: "h6-weight", variable: "--fontweight-h6", label: "h6 weight", unit: "", min: 100, max: 900, step: 10, default: 600 },
+	  { key: "weight-decay", variable: "--fontweight-decay", label: "Weight decay", unit: "", min: 0.5, max: 6, step: 0.1, default: 2 }
 	];
 	function themeSettings(theme) {
 	  return theme && typeof theme === "object" && !Array.isArray(theme) ?  (theme) : {}
@@ -19699,7 +19705,7 @@ ${fallback_html}`;
 	function rampValue(setting, value) {
 	  const clamped = Math.min(setting.max, Math.max(setting.min, value));
 	  const number = String(Number(clamped.toFixed(4)));
-	  if (setting.unit === "x") return `calc(${number} * var(--font-size-root))`
+	  if (setting.unit === "x") return `calc(${number} * var(--fontsize-root))`
 	  return `${number}${setting.unit}`
 	}
 	function typographyVariables(theme) {
@@ -20036,6 +20042,10 @@ ${fallback_html}`;
 	  if (properties.length) url.searchParams.set("properties", properties.join(","));
 	  return decodeURIComponent(url.pathname + url.search)
 	}
+	function alertLabel(type) {
+	  const spaced = type.replace(/[-_]+/g, " ");
+	  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+	}
 
 	const TEXT_NODE = 3;
 	const ELEMENT_NODE = 1;
@@ -20063,6 +20073,9 @@ ${fallback_html}`;
 	}
 	function expansionDirective(element) {
 	  const classes = classList(element);
+	  if (element.tagName === "FIGURE" && element.children.length === 1 && element.firstElementChild.tagName === "TABLE") {
+	    return expansionDirective(element.firstElementChild)
+	  }
 	  if ((element.tagName === "UL" || element.tagName === "TABLE") && classes.some(name => name.startsWith("_"))) {
 	    const params = globParams(classes);
 	    return params && globDirective(params)
@@ -20172,14 +20185,18 @@ ${fallback_html}`;
 	    })
 	  }
 	  if (tag === "ASIDE" && classList(element).includes("alert")) {
-	    const variant = classList(element).find(name => name !== "alert");
+	    const variant = classList(element).find(name => name !== "alert") || "note";
+	    const heading = [...element.children].find(child => child.tagName === "H2");
+	    const text = heading?.textContent.trim() ?? "";
+	    const title = text === alertLabel(variant) ? "" : text;
 	    const body = [...element.children]
-	      .filter(child => child.tagName !== "H2")
+	      .filter(child => child !== heading)
 	      .map(child => blockFrom(child, context));
 	    if (body.some(id => !id)) return null
 	    return context.create({
 	      type: "alert",
-	      variant: variant || "note",
+	      variant,
+	      title,
 	      body: { nodes: body, marks: [], annotations: [] }
 	    })
 	  }
@@ -20818,6 +20835,7 @@ ${fallback_html}`;
 	    kind: "block",
 	    properties: {
 	      variant: { type: "string", default: "note" },
+	      title: { type: "string", default: "" },
 	      body: { type: "node_array", node_types: BLOCK_TYPES, default_node_type: "paragraph" }
 	    }
 	  },
@@ -20970,12 +20988,26 @@ ${fallback_html}`;
 	    return { ...accumulated, [node.textContent.trim()]: valueFrom(value) }
 	  }, {})
 	}
+	function naturalLine(element) {
+	  const property = element.getAttribute("itemprop");
+	  if (property === "date") return element.textContent.trim()
+	  if (property === "description") return `${element.textContent.trim()}\n\n---`
+	  if (property !== "image") return null
+	  const img = element.tagName === "IMG" ? element : element.querySelector("img");
+	  const source = element.getAttribute("data-original") ?? img?.getAttribute("src");
+	  return source ? `![${img?.getAttribute("alt") ?? ""}](${source})` : null
+	}
 	function readFrontmatter(main) {
 	  const children = [...main.children];
+	  const declared = (key) => (child) => child.classList.contains(`fm_${key}`);
 	  const heading = children.find(child => child.tagName === "H1");
-	  const date = children.find(child => child.matches('time[itemprop="date"]'));
-	  const image = children.find(child => child.matches('picture[itemprop="image"]'));
-	  const description = children.find(child => child.matches('p[itemprop="description"]'));
+	  const date = children.find(declared("date"));
+	  const image = children.find(declared("image"));
+	  const description = children.find(declared("description"));
+	  const natural = children
+	    .filter(child => child.hasAttribute("itemprop") && ![...child.classList].some(name => name.startsWith("fm_")))
+	    .map(naturalLine)
+	    .filter(Boolean);
 	  const known = {
 	    ...(date ? { date: dateFrom(date) } : {}),
 	    ...(image ? { image: image.getAttribute("data-original") } : {}),
@@ -20986,7 +21018,9 @@ ${fallback_html}`;
 	    .reduce((accumulated, list) => ({ ...accumulated, ...objectFrom(list) }), {});
 	  return {
 	    title: heading ? heading.textContent.trim() : null,
-	    properties: { ...known, ...generic }
+	    titleDeclared: Boolean(heading?.classList.contains("fm_title")),
+	    properties: { ...known, ...generic },
+	    natural: natural.length ? `${natural.join("\n\n")}\n\n` : ""
 	  }
 	}
 

package/plugins/html/editor/Editor.svelte

@@ -29,17 +29,21 @@
   // socket pushes, so it is read at save time rather than when the
   // editor opened. Taking the frontmatter from the source rather than
   // the rendered page is what lets a key that never renders survive a
-  // save. The title is the one key that isn't kept: it is written back
-  // as a `#` heading, never as `title:`, so a file whose title lived
-  // only in frontmatter gains a heading and loses the key.
+  // save. A title declared in the frontmatter (`h1.fm_title`) stays a
+  // `title:` key; one from a `#` heading is written back as one. The
+  // natural metadata - a date line, an image, a description and its
+  // rule, lifted out of the content when the page was built - goes back
+  // between the heading and the body.
   async function save() {
     const { path, markdown: text } = getSource()
     if (!path || typeof text !== "string") {
       console.error("[vowel] not saved: this page has no source to save to")
       return
     }
-    const { title: ignoredTitle, ...properties } = splitFrontmatter(text).data
-    const markdown = serialize(session.doc, { title: frontmatter.title, properties })
+    const { title: sourceTitle, ...rest } = splitFrontmatter(text).data
+    const properties = frontmatter.titleDeclared ? { title: sourceTitle, ...rest } : rest
+    const title = frontmatter.titleDeclared ? null : frontmatter.title
+    const markdown = serialize(session.doc, { title, natural: frontmatter.natural, properties })
     await writeFile(path, markdown)
     console.info("[vowel] saved %s", path)
   }

package/plugins/html/editor/create-session.js

@@ -95,11 +95,13 @@ const document_schema = define_document_schema({
       body: { type: "node_array", node_types: BLOCK_TYPES, default_node_type: "paragraph" }
     }
   },
-  // > [!NOTE] - the variant is what the html plugin encodes in the class.
+  // > [!NOTE] Title - the variant is what the html plugin encodes in the
+  // class; the title is its heading, "" when it is the type's default.
   alert: {
     kind: "block",
     properties: {
       variant: { type: "string", default: "note" },
+      title: { type: "string", default: "" },
       body: { type: "node_array", node_types: BLOCK_TYPES, default_node_type: "paragraph" }
     }
   },

package/plugins/html/editor/directives.js

@@ -126,3 +126,15 @@ export function globDirective({ folder, recursive, limit, tag, view = null, prop
   if (properties.length) url.searchParams.set("properties", properties.join(","))
   return decodeURIComponent(url.pathname + url.search)
 }
+
+/**
+ * An alert's heading when the author gave it no title: its type in
+ * sentence case, `[!NOTE]` → "Note", `[!my-card]` → "My card". Here so
+ * the html plugin (which writes it) and the editor (which leaves it out
+ * on save) agree.
+ * @param {string} type - lowercase
+ */
+export function alertLabel(type) {
+  const spaced = type.replace(/[-_]+/g, " ")
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+}

package/plugins/html/editor/frontmatter.js

@@ -1,10 +1,13 @@
-// <main>'s children -> the page's frontmatter.
+// <main>'s children -> the page's frontmatter, and its natural metadata.
 //
-// The inverse of makeFrontmatter in plugins/html/index.js. Each property
-// is its own single-item <dl>, except the ones vowel handles specially,
-// which get their own element identified by itemprop. The title is main's
-// first <h1> - the one piece of data hoisted out of the content - and is
-// written back as a "#" heading rather than a frontmatter key.
+// The inverse of makeFrontmatter in plugins/html/index.js. A property
+// from the frontmatter carries its key as a class (`fm_date`,
+// `dl.fm_client`). The same properties written in the text - a date
+// line, an image, a description ended with a rule - are direct children
+// of <main> too, with their itemprop and no `fm_` class: those are
+// rebuilt as markdown, to go back at the top of the body. The title is
+// main's first <h1>: from the frontmatter when it has `fm_title`, else
+// from a "#" heading, and written back the same way.
 
 /** @param {Element} element */
 function scalarFrom(element) {
@@ -65,17 +68,43 @@ function objectFrom(list) {
   }, {})
 }
 
+/**
+ * One piece of natural metadata, back as the markdown that made it: the
+ * date line as the author wrote it, the image, the description and the
+ * rule that ended it. A description's inline marks are flattened to its
+ * text, the editor's usual lossy rule.
+ * @param {Element} element
+ * @returns {string|null}
+ */
+function naturalLine(element) {
+  const property = element.getAttribute("itemprop")
+  if (property === "date") return element.textContent.trim()
+  if (property === "description") return `${element.textContent.trim()}\n\n---`
+  if (property !== "image") return null
+
+  // A <picture>, or a plain <img> until the image has been read.
+  const img = element.tagName === "IMG" ? element : element.querySelector("img")
+  const source = element.getAttribute("data-original") ?? img?.getAttribute("src")
+  return source ? `![${img?.getAttribute("alt") ?? ""}](${source})` : null
+}
+
 /**
  * @param {Element} main
- * @returns {{title: string|null, properties: object}}
+ * @returns {{title: string|null, titleDeclared: boolean, properties: object, natural: string}}
  */
 export default function readFrontmatter(main) {
   const children = [...main.children]
+  const declared = (key) => (child) => child.classList.contains(`fm_${key}`)
 
   const heading = children.find(child => child.tagName === "H1")
-  const date = children.find(child => child.matches('time[itemprop="date"]'))
-  const image = children.find(child => child.matches('picture[itemprop="image"]'))
-  const description = children.find(child => child.matches('p[itemprop="description"]'))
+  const date = children.find(declared("date"))
+  const image = children.find(declared("image"))
+  const description = children.find(declared("description"))
+
+  const natural = children
+    .filter(child => child.hasAttribute("itemprop") && ![...child.classList].some(name => name.startsWith("fm_")))
+    .map(naturalLine)
+    .filter(Boolean)
 
   const known = {
     ...(date ? { date: dateFrom(date) } : {}),
@@ -92,6 +121,8 @@ export default function readFrontmatter(main) {
 
   return {
     title: heading ? heading.textContent.trim() : null,
-    properties: { ...known, ...generic }
+    titleDeclared: Boolean(heading?.classList.contains("fm_title")),
+    properties: { ...known, ...generic },
+    natural: natural.length ? `${natural.join("\n\n")}\n\n` : ""
   }
 }

package/plugins/html/editor/ingest.js

@@ -8,7 +8,7 @@
 // guess round-trips to markdown that silently replaces the author's
 // content on save.
 
-import { globParams, globDirective } from "./directives.js"
+import { globParams, globDirective, alertLabel } from "./directives.js"
 
 const TEXT_NODE = 3
 const ELEMENT_NODE = 1
@@ -51,7 +51,12 @@ function expansionDirective(element) {
   const classes = classList(element)
 
   // A glob list is a <ul>, or a <table> in its ?view=table form; the
-  // parameters are in the classes either way.
+  // parameters are in the classes either way. The table comes in a
+  // <figure>, which is only its frame.
+  if (element.tagName === "FIGURE" && element.children.length === 1 && element.firstElementChild.tagName === "TABLE") {
+    return expansionDirective(element.firstElementChild)
+  }
+
   if ((element.tagName === "UL" || element.tagName === "TABLE") && classes.some(name => name.startsWith("_"))) {
     const params = globParams(classes)
     return params && globDirective(params)
@@ -215,19 +220,25 @@ function blockFrom(element, context) {
   }
 
   if (tag === "ASIDE" && classList(element).includes("alert")) {
-    // > [!NOTE] became <aside class="alert note">, with the marker line
-    // replaced by an injected <h2>. The variant is the class; the injected
-    // heading is dropped and regenerated on the way out.
-    const variant = classList(element).find(name => name !== "alert")
+    // > [!NOTE] Title became <aside class="alert note"> with the title as
+    // an injected <h2>. The variant is the class. The heading is kept as
+    // the title, as plain text (inline marks in it are flattened, like
+    // any mark the editor can't hold), unless it is the default the html
+    // plugin made from the type - then there was no title to keep.
+    const variant = classList(element).find(name => name !== "alert") || "note"
+    const heading = [...element.children].find(child => child.tagName === "H2")
+    const text = heading?.textContent.trim() ?? ""
+    const title = text === alertLabel(variant) ? "" : text
     const body = [...element.children]
-      .filter(child => child.tagName !== "H2")
+      .filter(child => child !== heading)
       .map(child => blockFrom(child, context))
 
     if (body.some(id => !id)) return null
 
     return context.create({
       type: "alert",
-      variant: variant || "note",
+      variant,
+      title,
       body: { nodes: body, marks: [], annotations: [] }
     })
   }

package/plugins/html/editor/serialize.js

@@ -93,9 +93,10 @@ function blockFrom(id, nodes) {
     // The marker line the html plugin consumed is regenerated here. It is
     // emitted raw rather than as text: escaping would make it "\[!NOTE]",
     // which survives vowel's own parser but is not the literal GFM syntax.
+    const title = node.title ? ` ${node.title}` : ""
     const marker = {
       type: "html",
-      value: `[!${(node.variant || "note").toUpperCase()}]`
+      value: `[!${(node.variant || "note").toUpperCase()}]${title}`
     }
     const body = node.body.nodes.map(child => blockFrom(child, nodes))
     return { type: "blockquote", children: [marker, ...body] }
@@ -144,14 +145,17 @@ export default function serialize(doc, frontmatter = { title: null, properties:
     rule: "-"
   })
 
-  // The title is written as a heading rather than a frontmatter key, so a
-  // page whose title only ever lived in frontmatter gains one here.
+  // A title from a `#` heading is written back as one; a declared title
+  // arrives as null and stays in the properties.
   const heading = frontmatter.title ? `# ${frontmatter.title}\n\n` : ""
 
+  // The natural metadata (readFrontmatter), as markdown, already spaced.
+  const natural = frontmatter.natural || ""
+
   const properties = frontmatter.properties || {}
   const yaml = Object.keys(properties).length
     ? `---\n${stringifyYAML(properties)}---\n\n`
     : ""
 
-  return yaml + heading + body
+  return yaml + heading + natural + body
 }

package/plugins/html/image.js

@@ -69,7 +69,7 @@ function createDynamicImage(imagePath, api, alt, itemprop) {
   // Intrinsic size, measured at read (plugins/images): the browser
   // reserves the right box before the bytes arrive, and the reset's
   // `img { height: auto }` keeps the ratio when the width is capped.
-  const { width, height, dominant } = image.metadata
+  const { width, height, dominant, placeholder } = image.metadata
 
   const sources = formats.map((format, index) => {
     const isImg = index === formats.length - 1
@@ -91,13 +91,19 @@ function createDynamicImage(imagePath, api, alt, itemprop) {
   // The derivative paths in srcset are hash-based, so the original asset
   // path cannot be recovered from them. Carried here rather than as a
   // <source>, which is a loading candidate a browser could select.
-  // --dominant is the image's dominant colour, for a stylesheet to use
-  // as the placeholder behind a lazy image (`picture { background:
-  // var(--dominant) }`); nothing here decides that it should.
+  // Two values for a stylesheet to show behind the image while it loads:
+  // its dominant colour, and a tiny blurry copy (plugins/images; none
+  // for an image with transparency). Nothing here decides that it should.
+  const style = [
+    dominant && `--color-image-dominant: ${dominant}`,
+    // Unquoted: base64 has no character url() needs quoted, and the
+    // minifier would spell each quote as `&#34`.
+    placeholder && `--url-image-placeholder: url(${placeholder})`
+  ].filter(Boolean).join("; ")
   return h("picture", {
     itemprop: itemprop && "image",
     "data-original": imagePath,
-    style: dominant && `--dominant: ${dominant}`
+    style: style || undefined
   }, sources)
 }