vowel 0.7.1 → 0.7.3

package/bin.js

@@ -2,6 +2,7 @@
 
 import fs from "node:fs/promises"
 import os from "node:os"
+import path from "node:path"
 import { intro, note, text, select, confirm, spinner, outro, box, isCancel, cancel } from "@clack/prompts"
 import { parse } from "@bomb.sh/args"
 import t from "@bomb.sh/tab"
@@ -55,6 +56,22 @@ async function removeDatabase(verbose) {
   }
 }
 
+/**
+ * Empties the buffer cache: an image's measurements and derivative list,
+ * cached by votive so a warm start doesn't decode it again. Without
+ * this, a reset still reused every image's old read. Only the `.json`
+ * results go. The `cache-key` file stays, because votive empties a
+ * folder that has no key, so removing it would discard the next
+ * launch's fresh cache. URL fetches are not cached here.
+ * @param {boolean} verbose
+ */
+async function removeBufferCache(verbose) {
+  const entries = await fs.readdir(config.cacheDirectory).catch(() => [])
+  const results = entries.filter(name => name.endsWith(".json"))
+  await Promise.all(results.map(name => fs.rm(path.join(config.cacheDirectory, name), { force: true })))
+  if (verbose) console.info(`${styleText("dim", "loading:")} ${styleText("green", results.length ? "buffer cache cleared" : "no buffer cache found")}`)
+}
+
 /** @param {boolean} verbose */
 async function removeOutput(verbose) {
   try {
@@ -290,6 +307,7 @@ async function main() {
 
   if (shouldClear(args)) {
     await removeDatabase(args.logging === "verbose")
+    await removeBufferCache(args.logging === "verbose")
     await removeOutput(args.logging === "verbose")
   }
   await fs.mkdir(config.targetFolder, { recursive: true })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vowel",
   "type": "module",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "engines": {
     "node": ">=26"
   },
@@ -67,8 +67,7 @@
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "unpic": "^4.2.2",
-    "url-metadata": "^5.4.1",
-    "votive": "0.5.2",
+    "votive": "0.5",
     "xml": "^1.0.1",
     "yaml": "^2.8.2"
   },

package/plugins/atproto/body.js

@@ -113,7 +113,9 @@ function phrase(node, base) {
   }
   if (tag === "picture") {
     const img = (node.children ?? []).find(child => is(child, "img"))
-    const src = node.properties?.dataOriginal ?? img?.properties?.src
+    // The <img>'s src is the largest derivative in the image's own
+    // format; the original is not published (plugins/images).
+    const src = img?.properties?.src
     return src ? [{ type: "image", url: absolute(String(src), base), alt: String(img?.properties?.alt ?? "") }] : []
   }
   if (tag === "a") {

package/plugins/atproto/publish.js

@@ -11,6 +11,8 @@ import { PUBLICATION, siteOrigin, publicationURI, pageRecordURI } from "./record
 import { createLexiconResolver, resolvePDS } from "./lexicons.js"
 import { mapRecord } from "./mapper.js"
 import { markdownBody, richTextBody } from "./body.js"
+import { imageURL } from "../html/image.js"
+import { imageSizes } from "../../utils.js"
 
 /**
  * `vowel --command atproto-publish`: make the account's records match the
@@ -267,7 +269,9 @@ function recordPages(database) {
  * its status, and what mapper.js reads - the site's own settings, and
  * the publication's name, description and icon. The icon is read from
  * the build's output - it is a URL path from the root (frontmatter.js
- * resolves it), which is where the output has it. Built into a scratch
+ * resolves it), which is where the output has it; a png or jpeg is read
+ * from its largest derivative, since the original is not published
+ * (plugins/images). Built into a scratch
  * folder that is removed afterwards.
  * @param {import("votive").VotiveConfig} config
  */
@@ -306,7 +310,9 @@ async function collectPages(config) {
       const home = site.database.target.get("index.html")
       const name = root.raw("fm_name")?.[0]?.at(-1) ?? (home?.source ? home.metadata.title : undefined)
       const iconPath = settings.icon ?? root.lastNonNull("logo")
-      const icon = iconPath ? await readIcon(path.join(scratch, "output"), iconPath) : undefined
+      // imageURL asks an api for the target; the database answers the same.
+      const builtIcon = imageURL(iconPath, { target: (targetPath) => site.database.target.get(targetPath) }, imageSizes.at(-1))
+      const icon = builtIcon ? await readIcon(path.join(scratch, "output"), builtIcon) : undefined
       const publication = { name, description: settings.description, iconPath, icon }
       return { did, pds, domain, pages, publication }
     } finally {

package/plugins/html/bundle/index.js

@@ -20156,7 +20156,7 @@ ${fallback_html}`;
 	  const tag = element.tagName;
 	  if (tag === "P") {
 	    const picture = pictureIn(element);
-	    if (picture && !element.textContent.trim()) return imageFrom(picture, null, element, context)
+	    if (picture && !element.textContent.trim()) return imageFrom(context)
 	    return context.create({
 	      type: "paragraph",
 	      content: textValue(element, context)
@@ -20224,29 +20224,17 @@ ${fallback_html}`;
 	  }
 	  if (tag === "FIGURE") {
 	    const picture = pictureIn(element);
-	    const caption = element.querySelector("figcaption");
-	    if (picture) return imageFrom(picture, caption, element, context)
+	    if (picture) return imageFrom(context)
 	  }
 	  if (tag === "PICTURE") {
-	    return imageFrom(element, null, element, context)
+	    return imageFrom(context)
 	  }
 	  context.unrecognised.push(tag.toLowerCase() + (element.className ? `.${element.className}` : ""));
 	  return null
 	}
-	function imageFrom(picture, caption, outer, context) {
-	  const img = picture.querySelector("img");
-	  const source = picture.getAttribute("data-original");
-	  if (!source) {
-	    context.unrecognised.push("picture (no data-original)");
-	    return null
-	  }
-	  return context.create({
-	    type: "image",
-	    source,
-	    alt: img ? (img.getAttribute("alt") || "") : "",
-	    caption: caption ? caption.textContent : "",
-	    html: outer.outerHTML
-	  })
+	function imageFrom(context) {
+	  context.unrecognised.push("picture");
+	  return null
 	}
 	function ingest(contentElement, generateId) {
 	  const nodes = {};
@@ -20989,28 +20977,42 @@ ${fallback_html}`;
 	  }, {})
 	}
 	function naturalLine(element) {
+	  if (element.tagName === "FIGURE") return figureLine(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
+	  if (element.tagName !== "IMG") return null
+	  const source = element.getAttribute("src");
+	  return source ? `![${element.getAttribute("alt") ?? ""}](${source})` : null
+	}
+	function figureLine(figure) {
+	  const image = figure.querySelector(":scope > [itemprop=image]");
+	  const line = image ? naturalLine(image) : null;
+	  if (!line) return null
+	  const caption = figure.querySelector(":scope > figcaption")?.textContent.trim();
+	  return caption ? `${line} ${caption}` : line
+	}
+	function isNatural(child) {
+	  if ([...child.classList].some(name => name.startsWith("fm_"))) return false
+	  if (child.hasAttribute("itemprop")) return true
+	  return child.tagName === "FIGURE" && Boolean(child.querySelector(":scope > [itemprop=image]"))
 	}
 	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(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_")))
+	  const naturalChildren = children.filter(isNatural);
+	  const natural = naturalChildren
 	    .map(naturalLine)
 	    .filter(Boolean);
+	  const unrecognised = naturalChildren
+	    .filter(child => child.tagName === "PICTURE" || child.querySelector("picture"))
+	    .map(() => "picture");
 	  const known = {
 	    ...(date ? { date: dateFrom(date) } : {}),
-	    ...(image ? { image: image.getAttribute("data-original") } : {}),
 	    ...(description ? { description: description.textContent.trim() } : {})
 	  };
 	  const generic = children
@@ -21020,7 +21022,8 @@ ${fallback_html}`;
 	    title: heading ? heading.textContent.trim() : null,
 	    titleDeclared: Boolean(heading?.classList.contains("fm_title")),
 	    properties: { ...known, ...generic },
-	    natural: natural.length ? `${natural.join("\n\n")}\n\n` : ""
+	    natural: natural.length ? `${natural.join("\n\n")}\n\n` : "",
+	    unrecognised
 	  }
 	}
 
@@ -21044,7 +21047,10 @@ ${fallback_html}`;
 	  socket.addEventListener('message', e => {
 	    if (!isOpen()) return
 	    const target = JSON.parse(e.data);
-	    if (target.extension !== ".html") return
+	    if (target.extension !== ".html") {
+	      retryImages("/" + target.path);
+	      return
+	    }
 	    const regex = new RegExp(window.location.pathname + "(index)?(\\.html)");
 	    if (!("/" + target.path).match(regex)) return
 	    updateFromTarget(target);
@@ -21131,6 +21137,19 @@ ${fallback_html}`;
 	    if (!produced.has(keyOf(element)) && wasProduced(element)) element.remove();
 	  }
 	}
+	function retryImages(url) {
+	  const failed = [...document.images].filter(img => img.complete && img.naturalWidth === 0);
+	  const elements = failed.map(img => img.parentElement?.tagName === "PICTURE" ? img.parentElement : img);
+	  const naming = elements.filter(element => urlsOf(element).includes(url));
+	  for (const element of naming) element.replaceWith(element.cloneNode(true));
+	}
+	function urlsOf(element) {
+	  const nodes = [element, ...element.querySelectorAll("source, img")];
+	  return nodes.flatMap(node => {
+	    const candidates = (node.getAttribute("srcset") ?? "").split(",").map(candidate => candidate.trim().split(/\s+/)[0]);
+	    return [node.getAttribute("src"), ...candidates].filter(Boolean)
+	  })
+	}
 	function wasProduced(element) {
 	  if (element.tagName === "SCRIPT") return false
 	  if (element.hasAttribute("data-vowel-client")) return false
@@ -21139,7 +21158,7 @@ ${fallback_html}`;
 
 	openSocket();
 	const content = document.getElementById("content");
-	const noFrontmatter = { title: null, properties: {} };
+	const noFrontmatter = { title: null, properties: {}, unrecognised: [] };
 	function startEditing() {
 	  const { session, unrecognised } = create_session(content);
 	  if (!session) {
@@ -21151,6 +21170,10 @@ ${fallback_html}`;
 	  }
 	  const main = content.closest("main");
 	  const frontmatter = main ? readFrontmatter(main) : noFrontmatter;
+	  if (frontmatter.unrecognised.length) {
+	    console.warn("[vowel] editor stayed read-only: <main> holds natural metadata it can't write back:", frontmatter.unrecognised);
+	    return frontmatter.unrecognised
+	  }
 	  content.replaceChildren();
 	  mount(Editor, { target: content, props: { session, frontmatter } });
 	  document.documentElement.dataset.vowelEditing = "true";

package/plugins/html/editor/frontmatter.js

@@ -77,20 +77,49 @@ function objectFrom(list) {
  * @returns {string|null}
  */
 function naturalLine(element) {
+  if (element.tagName === "FIGURE") return figureLine(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
+  // A plain <img> links the path as written. A <picture> names only its
+  // derivatives, so it can't be written back, and readFrontmatter
+  // reports it.
+  if (element.tagName !== "IMG") return null
+  const source = element.getAttribute("src")
+  return source ? `![${element.getAttribute("alt") ?? ""}](${source})` : null
+}
+
+/**
+ * A captioned image, back as the image and its caption on one line. The
+ * caption's inline marks are flattened to its text, as a description's
+ * are and as ingest does for a captioned image in the content.
+ * @param {Element} figure
+ * @returns {string|null}
+ */
+function figureLine(figure) {
+  const image = figure.querySelector(":scope > [itemprop=image]")
+  const line = image ? naturalLine(image) : null
+  if (!line) return null
+  const caption = figure.querySelector(":scope > figcaption")?.textContent.trim()
+  return caption ? `${line} ${caption}` : line
+}
+
+/**
+ * A captioned image carries its itemprop on the image inside its
+ * <figure>, so the figure is natural metadata when that image is.
+ * @param {Element} child - of <main>
+ */
+function isNatural(child) {
+  if ([...child.classList].some(name => name.startsWith("fm_"))) return false
+  if (child.hasAttribute("itemprop")) return true
+  return child.tagName === "FIGURE" && Boolean(child.querySelector(":scope > [itemprop=image]"))
 }
 
 /**
  * @param {Element} main
- * @returns {{title: string|null, titleDeclared: boolean, properties: object, natural: string}}
+ * @returns {{title: string|null, titleDeclared: boolean, properties: object, natural: string, unrecognised: string[]}}
  */
 export default function readFrontmatter(main) {
   const children = [...main.children]
@@ -98,17 +127,21 @@ export default function readFrontmatter(main) {
 
   const heading = children.find(child => child.tagName === "H1")
   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_")))
+  const naturalChildren = children.filter(isNatural)
+  const natural = naturalChildren
     .map(naturalLine)
     .filter(Boolean)
+  // A natural image that is a <picture> can't be written back
+  // (naturalLine), so the page stays read-only rather than losing the
+  // line on save.
+  const unrecognised = naturalChildren
+    .filter(child => child.tagName === "PICTURE" || child.querySelector("picture"))
+    .map(() => "picture")
 
   const known = {
     ...(date ? { date: dateFrom(date) } : {}),
-    ...(image ? { image: image.getAttribute("data-original") } : {}),
     ...(description ? { description: description.textContent.trim() } : {})
   }
 
@@ -123,6 +156,7 @@ export default function readFrontmatter(main) {
     title: heading ? heading.textContent.trim() : null,
     titleDeclared: Boolean(heading?.classList.contains("fm_title")),
     properties: { ...known, ...generic },
-    natural: natural.length ? `${natural.join("\n\n")}\n\n` : ""
+    natural: natural.length ? `${natural.join("\n\n")}\n\n` : "",
+    unrecognised
   }
 }

package/plugins/html/editor/ingest.js

@@ -185,7 +185,7 @@ function blockFrom(element, context) {
     // The image transform replaces an <img> in place, so a paragraph whose
     // only element is a <picture> is an image block, not prose.
     const picture = pictureIn(element)
-    if (picture && !element.textContent.trim()) return imageFrom(picture, null, element, context)
+    if (picture && !element.textContent.trim()) return imageFrom(context)
 
     return context.create({
       type: "paragraph",
@@ -274,12 +274,11 @@ function blockFrom(element, context) {
 
   if (tag === "FIGURE") {
     const picture = pictureIn(element)
-    const caption = element.querySelector("figcaption")
-    if (picture) return imageFrom(picture, caption, element, context)
+    if (picture) return imageFrom(context)
   }
 
   if (tag === "PICTURE") {
-    return imageFrom(element, null, element, context)
+    return imageFrom(context)
   }
 
   context.unrecognised.push(tag.toLowerCase() + (element.className ? `.${element.className}` : ""))
@@ -287,26 +286,14 @@ function blockFrom(element, context) {
 }
 
 /**
- * @param {Element} picture
- * @param {Element|null} caption
- * @param {Element} outer the element whose markup is kept for rendering
+ * An image can't be edited yet. Its <picture> names only the image's
+ * derivatives, and the path the author wrote is not in the page (per
+ * Sam, the output carries no data-original for the editor), so a save
+ * could only guess it. It is reported, which leaves the page read-only.
  */
-function imageFrom(picture, caption, outer, context) {
-  const img = picture.querySelector("img")
-  const source = picture.getAttribute("data-original")
-
-  if (!source) {
-    context.unrecognised.push("picture (no data-original)")
-    return null
-  }
-
-  return context.create({
-    type: "image",
-    source,
-    alt: img ? (img.getAttribute("alt") || "") : "",
-    caption: caption ? caption.textContent : "",
-    html: outer.outerHTML
-  })
+function imageFrom(context) {
+  context.unrecognised.push("picture")
+  return null
 }
 
 /**

package/plugins/html/editor/main.js

@@ -15,7 +15,7 @@ openSocket()
 // document's source of truth (see ingest.js).
 const content = document.getElementById("content")
 
-const noFrontmatter = { title: null, properties: {} }
+const noFrontmatter = { title: null, properties: {}, unrecognised: [] }
 
 /**
  * Swaps the server-rendered body for the editor. A previewed page runs
@@ -50,6 +50,10 @@ function startEditing() {
   // them is what lets a save reproduce the whole file.
   const main = content.closest("main")
   const frontmatter = main ? readFrontmatter(main) : noFrontmatter
+  if (frontmatter.unrecognised.length) {
+    console.warn("[vowel] editor stayed read-only: <main> holds natural metadata it can't write back:", frontmatter.unrecognised)
+    return frontmatter.unrecognised
+  }
 
   // Svedit renders the document itself rather than hydrating over the
   // server output, so the original children go before it mounts.

package/plugins/html/editor/socket.js

@@ -51,10 +51,12 @@ export default function openSocket() {
 
     const target = JSON.parse(e.data)
 
-    // Nothing here knows what a non-html target should do on change yet -
-    // that's each content type's own concern to add, same as html's own
-    // patch logic below isn't generic.
-    if (target.extension !== ".html") return
+    // A file that isn't a page can only matter to this page as something
+    // it loads: an image the page named before its file existed.
+    if (target.extension !== ".html") {
+      retryImages("/" + target.path)
+      return
+    }
 
     const regex = new RegExp(window.location.pathname + "(index)?(\\.html)")
     if (!("/" + target.path).match(regex)) return
@@ -185,6 +187,34 @@ function patchBody(body, nextBody) {
   }
 }
 
+/**
+ * A page can arrive before the image files it names: an image's
+ * derivatives are encoded after the page is written, and a browser never
+ * asks again for an image that failed. When a file lands, every image
+ * that failed and names it is replaced with a copy of itself, which
+ * asks again. A <picture> is copied whole, so its <source>s are chosen
+ * from again too.
+ * @param {string} url - the file's url, from the root
+ */
+function retryImages(url) {
+  const failed = [...document.images].filter(img => img.complete && img.naturalWidth === 0)
+  const elements = failed.map(img => img.parentElement?.tagName === "PICTURE" ? img.parentElement : img)
+  const naming = elements.filter(element => urlsOf(element).includes(url))
+  for (const element of naming) element.replaceWith(element.cloneNode(true))
+}
+
+/**
+ * Every url an <img> or a <picture> could load.
+ * @param {Element} element
+ */
+function urlsOf(element) {
+  const nodes = [element, ...element.querySelectorAll("source, img")]
+  return nodes.flatMap(node => {
+    const candidates = (node.getAttribute("srcset") ?? "").split(",").map(candidate => candidate.trim().split(/\s+/)[0])
+    return [node.getAttribute("src"), ...candidates].filter(Boolean)
+  })
+}
+
 /**
  * The client adds elements that aren't the build's: the editor's own
  * <script type="module">, and whatever Svelte mounts into the body (the

package/plugins/html/image.js

@@ -1,10 +1,71 @@
-import { testURL, createImagePaths, imageSizes, imageExts } from "./../../utils.js"
+import { testURL, imageSizes, imageExts } from "./../../utils.js"
 import path from "node:path"
 import { h } from 'hastscript'
 import * as unpic from "unpic"
 
 /** @import * as Votive from "votive" */
 
+/**
+ * The image target a path names, from the root. Lowercased: every vowel
+ * target path is (config.js's router), and the author may well have
+ * typed the file's real name.
+ * @param {string} imagePath
+ * @param {import("votive").PluginAPI} api
+ */
+function findImage(imagePath, api) {
+  const relativePath = (imagePath.startsWith("/") ? path.relative("/", imagePath) : imagePath).toLowerCase()
+  return api.target(relativePath)
+}
+
+/**
+ * The derivative to link where one file goes rather than a srcset: in
+ * the image's own format, at `size` (one of imageSizes). Undefined for
+ * an image without derivatives (plugins/images: a format that isn't
+ * optimised, the root favicon.png, or an image not read yet).
+ * @param {any} image - the image's target
+ * @param {number} size
+ */
+function derivativeURL(image, size) {
+  const format = path.extname(image.path).slice(1)
+  const derivative = image.metadata?.derivatives?.find(entry => entry.format === format && entry.size === size)
+  if (!derivative) return
+  return "/" + derivative.path
+}
+
+/**
+ * The url to put where an image path goes as one file - og:image, the
+ * logo, an icon. A png or jpeg is not published at full size
+ * (plugins/images), so the path names a derivative; anything else, an
+ * external url included, is returned as it is. A tracked read, so the
+ * page is rewritten when the image is read or changes.
+ * @param {string | undefined} imagePath - from the root
+ * @param {import("votive").PluginAPI} api
+ * @param {number} size - one of imageSizes
+ */
+function imageURL(imagePath, api, size) {
+  if (!imagePath || testURL(imagePath) || !/\.(png|jpe?g)$/i.test(imagePath)) return imagePath
+  const image = findImage(imagePath, api)
+  if (!image) return imagePath
+  return derivativeURL(image, size) ?? imagePath
+}
+
+/**
+ * The page image's dominant colour as a style for the element that
+ * holds it - a page's <main>, a card's <article> - so CSS outside the
+ * image can use it (text that contrasts with it, say). The <picture>
+ * carries it too, for its own placeholder. Nothing here decides that
+ * anything should use it. Undefined for no image, an external one, or
+ * one not read yet.
+ * @param {string | undefined} imagePath - from the root
+ * @param {import("votive").PluginAPI} api
+ */
+function dominantStyle(imagePath, api) {
+  if (!imagePath || testURL(imagePath)) return
+  const dominant = findImage(imagePath, api)?.metadata.dominant
+  if (!dominant) return
+  return `--color-image-dominant: ${dominant}`
+}
+
 /**
  * @param {string} imagePath
  * @param {import("votive").PluginAPI} api
@@ -45,26 +106,23 @@ 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.
-  return h("picture", { itemprop: itemprop && "image", "data-original": imagePath }, sources)
+      return h("picture", { itemprop: itemprop && "image" }, sources)
     }
   }
 
   if (!isImg) return
 
-  // Lowercased: every vowel target path is (config.js's router), and
-  // the author may well have typed the file's real name.
-  const relativePath = (imagePath.startsWith("/") ? path.relative("/", imagePath) : imagePath).toLowerCase()
-  const image = api.target(relativePath)
+  const image = findImage(imagePath, api)
   if (!image) return
-  // Until the image has been read (a deferred buffer read) it has no
-  // hash and no derivatives; a plain <img> stands in, and the tracked
-  // read of `hash` rewrites this page when they arrive. Derivatives are
-  // named from the *target* path, as the images processor declares them.
-  if (!image.metadata.hash) return h("img", { src: "/" + image.path, alt, loading: "lazy" })
-  const formats = createImagePaths(image.path, "./", image.metadata.hash)
+  // An image without derivatives is published as it is (the root
+  // favicon.png), and a plain <img> links it. The tracked read of
+  // `derivatives` rewrites this page if they arrive.
+  const { derivatives } = image.metadata
+  if (!derivatives) return h("img", { src: "/" + image.path, alt, loading: "lazy" })
+  // One group per format, in the order the read lists them, which is
+  // <picture> order: avif, webp, then the image's own format as the <img>.
+  const formats = [...new Set(derivatives.map(entry => entry.format))]
+    .map(format => derivatives.filter(entry => entry.format === format))
 
   // Intrinsic size, measured at read (plugins/images): the browser
   // reserves the right box before the bytes arrive, and the reset's
@@ -74,13 +132,13 @@ function createDynamicImage(imagePath, api, alt, itemprop) {
   const sources = formats.map((format, index) => {
     const isImg = index === formats.length - 1
 
-    const sizes = format.map((size, index) => `/${size} ${imageSizes[index]}w`).join(", ")
-    const type = "image/" + path.extname(format[0]).slice(1)
+    const sizes = format.map(entry => `/${entry.path} ${entry.size}w`).join(", ")
+    const type = "image/" + format[0].format
     return h(isImg ? "img" : "source", {
       type,
       srcset: sizes,
       loading: isImg && "lazy",
-      src: isImg && "/" + format.at(-1),
+      src: isImg && "/" + format.at(-1).path,
       sizes: "100vw",
       width: isImg && width,
       height: isImg && height,
@@ -88,9 +146,6 @@ 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.
   // 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.
@@ -102,9 +157,9 @@ function createDynamicImage(imagePath, api, alt, itemprop) {
   ].filter(Boolean).join("; ")
   return h("picture", {
     itemprop: itemprop && "image",
-    "data-original": imagePath,
     style: style || undefined
   }, sources)
 }
 
+export { dominantStyle, imageURL, derivativeURL }
 export default createDynamicImage

package/plugins/html/index.js

@@ -13,14 +13,14 @@ import { gfmTable } from 'micromark-extension-gfm-table'
 import { gfmTableFromMarkdown } from 'mdast-util-gfm-table'
 import { h } from 'hastscript'
 import { readFileSync } from "fs"
-import { testURL, testHashtags, createHashtagPage, labelFromName, isPageWithoutFile, pageClasses, hashtagRegexSingle, createImagePaths, imageSizes, imageExts } from "./../../utils.js"
+import { testURL, testHashtags, createHashtagPage, labelFromName, isPageWithoutFile, pageClasses, hashtagRegexSingle, imageSizes } from "./../../utils.js"
 import extractDate from "./../../extractDate.js"
 import { reservedProperties, hiddenProperties } from "./../markdown/metadata.js"
 import { toString as hastToString } from 'hast-util-to-string'
 import { unified } from "unified"
 import toc from "@jsdevtools/rehype-toc"
 import slug from "rehype-slug"
-import createDynamicImage from "./image.js"
+import createDynamicImage, { dominantStyle, imageURL } from "./image.js"
 import { listPages } from "./../../utils.js"
 import { pageRecordURI } from "../atproto/record.js"
 import { STATUSES } from "../markdown/frontmatter.js"
@@ -92,9 +92,8 @@ function makeHeader(metadata, url, api, config, source) {
     treeMainHead.push(makeTime(date))
   }
 
-  if (metadata.image || metadata.first_image) {
-    const metaImage = metadata.image || metadata.first_image
-
+  const metaImage = metadata.image || metadata.first_image
+  if (metaImage) {
     treeMainHead.push(
       createDynamicImage(metaImage, api, null, true)
     )
@@ -113,7 +112,12 @@ function makeHeader(metadata, url, api, config, source) {
   // an item of its own: the itemprops inside it (date, description,
   // image) describe that page, not the page it's listed on. A page with
   // no file (`html_file: false`) has no url, so its card links nowhere.
-  const article = h('article', { className: pageClasses(metadata.prettyURL, source), itemscope: true }, treeMainHead)
+  // Its image's dominant colour is the card's, for the card's own CSS.
+  const article = h('article', {
+    className: pageClasses(metadata.prettyURL, source),
+    itemscope: true,
+    style: dominantStyle(metaImage, api)
+  }, treeMainHead)
   return url ? h('a', { href: url }, article) : article
 }
 
@@ -251,6 +255,13 @@ function naturalMetadata(tree) {
     const { dataMetadata: kind, ...properties } = node.properties
     if (kind === "end") return []
     if (kind === "description") return [{ ...node, properties }]
+    // A captioned image is a <figure> (writeRules.js) and is lifted
+    // whole. The itemprop goes on its image, not the figure: an image is
+    // the property, and the caption is not part of it.
+    if (node.tagName === "figure") {
+      const [image, ...caption] = node.children
+      return [{ ...node, properties, children: [{ ...image, properties: { ...image.properties, itemprop: kind } }, ...caption] }]
+    }
     // A date or an image paragraph only wrapped the one element that is
     // the metadata: the <time>, or the <picture> (an <img> until the
     // image has been read).
@@ -545,7 +556,9 @@ function writeFile(target, { settings, api, config }) {
 
   // The page's own image, else the site's `fallback_image` (a setting,
   // so a folder can have its own), so a link preview always has one.
-  const ogImage = metadata.image || settings.lastNonNull("fm_fallback_image")
+  // The largest derivative of a png or jpeg (image.js): the original
+  // is not published.
+  const ogImage = imageURL(metadata.image || settings.lastNonNull("fm_fallback_image"), api, imageSizes.at(-1))
   if (ogImage) {
     treeHead.children.push(h("meta", {
       property: "og:image",
@@ -568,7 +581,7 @@ function writeFile(target, { settings, api, config }) {
   // right one lets it pick between several. Without one, the project's
   // own favicon.png, else Vowel's placeholder (plugins/images). A
   // tracked read, so a favicon.png that appears later is linked.
-  const icon = settings.lastNonNull("fm_icon")
+  const icon = imageURL(settings.lastNonNull("fm_icon"), api, imageSizes[0])
     ?? (api.target("favicon.png") ? "/favicon.png" : "/favicon-placeholder.png")
   treeHead.children.push(h("link", {
     href: icon,
@@ -609,8 +622,10 @@ function writeFile(target, { settings, api, config }) {
   const homeLink = []
 
 
-  const logo = settings.lastNonNull("logo")
-  const wordmark = settings.lastNonNull("fm_wordmark")
+  // The smallest derivative of a png or jpeg (image.js): the original
+  // is not published. An SVG is linked as it is.
+  const logo = imageURL(settings.lastNonNull("logo"), api, imageSizes[0])
+  const wordmark = imageURL(settings.lastNonNull("fm_wordmark"), api, imageSizes[0])
 
   const identityElements = []
 
@@ -647,7 +662,7 @@ function writeFile(target, { settings, api, config }) {
   const treeHeader = h('header', [
     identity,
     treeNav,
-    socialLinksNav(settings)
+    socialLinksNav(settings, api)
   ])
 
 
@@ -699,7 +714,9 @@ function writeFile(target, { settings, api, config }) {
 
   const treeMain = h('main',
     {
-      itemscope: true
+      itemscope: true,
+      // The page image's dominant colour, for anything in <main> to use.
+      style: dominantStyle(metadata.image, api)
     },
     [
       // The title is main's first child: the one piece of data hoisted out
@@ -723,7 +740,7 @@ function writeFile(target, { settings, api, config }) {
   const treeAside = asideNav ? h("aside", asideNav) : null
 
   const treeFooter = h('footer', [
-    socialLinksNav(settings),
+    socialLinksNav(settings, api),
     h('section#copyright', `© ${new Date().getFullYear()}`),
     h('section#shoutout', [
       "Made with ",

package/plugins/html/partials.js

@@ -41,9 +41,23 @@ const PROJECT_SHEET = "styles.css"
 
 const ASIDE_PARTIAL = path.join("partials", "aside.partial")
 
-/** A page with more siblings than this is left out of the aside. */
+/** A page with more siblings than this is left out of the aside and the header nav. */
 const MAX_SIBLINGS = 18
 
+/**
+ * A folder's pages as a menu, or none: a page with more than
+ * MAX_SIBLINGS siblings is left out, and so are its siblings. Their
+ * folder's own entry stays, and its pages are a listing's job, not a
+ * menu's. Per Sam: "exclude pages with 19 siblings or more", and the
+ * header nav follows the same rule as the aside. Without it, a folder
+ * of 4,000 undated notes put a 4,000-link nav on each of them: 352 KB of
+ * a 355 KB page, and a build that grew with the square of the folder.
+ * @template T
+ * @param {T[]} pages - one folder's
+ * @returns {T[]}
+ */
+const asMenu = (pages) => pages.length - 1 > MAX_SIBLINGS ? [] : pages
+
 /** @param {string} targetPath - the page's own target path */
 function backlinksPartialPath(targetPath) {
   return path.join("partials", "backlinks", `${targetPath}.partial`)
@@ -103,19 +117,16 @@ function asideTree(pages) {
     if (!byFolder.has(url)) byFolder.set(url, [])
     byFolder.get(url).push(page)
   }
-  // A page with more than MAX_SIBLINGS siblings is left out, and so are
-  // its siblings: the folder's own entry stays, and its pages are a
-  // listing's job, not a menu's. Per Sam: "exclude pages with 19
-  // siblings or more".
+  // A folder with too many pages for a menu shows its own entry only (asMenu).
   const children = (parent) => {
     const pages = byFolder.get(parent.metadata.prettyURL) ?? []
-    return pages.length - 1 > MAX_SIBLINGS ? [] : pages.map(node)
+    return asMenu(pages).map(node)
   }
 
   function node(page) {
     const below = children(page)
     // The aside links the file, not the pretty url - kept as it was
-    // (see the note in the commit); the home entry is the bare path.
+    // (see the note in the commit).
     return { url: "/" + page.path, label: page.metadata.breadcrumb, ...(below.length ? { children: below } : {}) }
   }
 
@@ -124,7 +135,9 @@ function asideTree(pages) {
       && isOn(page.metadata.global_nav_item) && isOn(page.metadata.html_file))
     .map(node)
 
-  return [...(home ? [{ url: home.path, label: home.metadata.breadcrumb }] : []), ...top]
+  // The home entry is the root's url: its bare path, `index.html`, is
+  // relative, and from /blog/post it named /blog/index.html.
+  return [...(home ? [item(home)] : []), ...top]
 }
 
 /**
@@ -224,7 +237,12 @@ function createPartialStubs(api) {
   const navs = [...folders].sort().map(folder => ({
     path: navPartialPath(folder),
     params: {
-      levels: chain(folder).map(level => (lists.get(level) ?? []).map(item)),
+      // The root's pages are the top of the menu, as in the aside; below
+      // it, a folder with too many pages shows none of them (asMenu).
+      levels: chain(folder).map(level => {
+        const list = lists.get(level) ?? []
+        return (level ? asMenu(list) : list).map(item)
+      }),
       sheets: chain(folder).flatMap(level => sheets.get(level) ?? [])
     }
   }))

package/plugins/html/socialLinks.js

@@ -1,4 +1,6 @@
 import { h } from "hastscript"
+import { imageSizes } from "../../utils.js"
+import { imageURL } from "./image.js"
 
 /**
  * Social links, from the `social_links` setting:
@@ -45,16 +47,19 @@ function socialLinks(settings) {
 /**
  * A `<nav>` of the links, or null when there are none.
  * @param {any} settings
+ * @param {import("votive").PluginAPI} api
  */
-function socialLinksNav(settings) {
+function socialLinksNav(settings, api) {
   const links = socialLinks(settings)
   if (!links.length) return null
 
   return h("nav.social-links", { "aria-label": "Social links" },
     h("ul", links.map(({ label, url, icon }) => {
       const text = label ?? url
-      // A URL path from the root, resolved at read (frontmatter.js).
-      const iconURL = icon ? String(icon) : null
+      // A URL path from the root, resolved at read (frontmatter.js); a
+      // png or jpeg's smallest derivative, since the original is not
+      // published (image.js).
+      const iconURL = icon ? imageURL(String(icon), api, imageSizes[0]) : null
       const image = iconURL && h("img", { src: iconURL, alt: text, style: `--url-icon: url("${iconURL}")` })
       return h("li", h("a", { href: url, rel: "me" }, image || text))
     }))

package/plugins/html/writeRules.js

@@ -4,9 +4,9 @@ import { common, createLowlight } from "lowlight"
 import { toText } from "hast-util-to-text"
 import GithubSlugger from "github-slugger"
 import { createVisitor, SKIP } from "../markdown/visitor.js"
-import { showPages, isPageWithoutFile } from "../../utils.js"
+import { showPages, isPageWithoutFile, imageSizes } from "../../utils.js"
 import { globClasses, alertLabel } from "./editor/directives.js"
-import createDynamicImage from "./image.js"
+import createDynamicImage, { derivativeURL } from "./image.js"
 import { displayPath } from "../../secretPaths.js"
 
 /**
@@ -139,7 +139,9 @@ const internalLink = {
       if (!readInBackground(pathname, config)) config.log?.("warn", `${target.source ?? target.path}: link to ${href} matches no page`)
       return
     }
-    node.properties.href = urlOf(found) + suffix
+    // A link to a png or jpeg opens its largest derivative: the
+    // original is not published (image.js).
+    node.properties.href = (derivativeURL(found, imageSizes.at(-1)) ?? urlOf(found)) + suffix
   }
 }
 
@@ -291,14 +293,42 @@ const highlight = {
   }
 }
 
+/** The stand-in size of an image not read yet: 3:2, the commonest photo shape. */
+const PENDING_WIDTH = 1500
+const PENDING_HEIGHT = 1000
+
+/** An image in the text, not an inline icon (`:folder/name:`). @param {any} node */
+const isImage = (node) => isElement(node) && node.tagName === "img" && !hasClass(node, "icon")
+
 /**
- * A project image becomes a responsive <picture>; first in its
- * paragraph with siblings after it, those are its caption.
+ * A paragraph that starts with an image and goes on is a captioned
+ * image: the paragraph becomes a <figure>, and what follows the image
+ * its <figcaption>. In place, so the walk goes on into both (the image
+ * rule makes the <picture>, the inline rules read the caption) and a
+ * natural image's mark (`data-metadata`) stays on the element the html
+ * plugin lifts. The <figure> used to go inside the <p>, where it is not
+ * allowed: a browser closed the paragraph before it and left an empty
+ * one behind.
+ * @type {import("../markdown/visitor.js").BlockRule}
+ */
+const captionedImage = {
+  name: "captioned image",
+  test: (node) => isElement(node) && node.tagName === "p" && isImage(node.children?.[0])
+    && node.children.slice(1).some(child => child.type !== "text" || child.value.trim()),
+  transform: (node) => {
+    const [img, ...caption] = node.children
+    node.tagName = "figure"
+    node.children = [img, h("figcaption", caption)]
+  }
+}
+
+/**
+ * A project image becomes a responsive <picture>.
  * @type {import("../markdown/visitor.js").BlockRule}
  */
 const image = {
   name: "image",
-  test: (node) => isElement(node) && node.tagName === "img" && !hasClass(node, "icon"),
+  test: isImage,
   transform: (node, index, parent, context) => {
     const { api, target } = context
     const { src, alt } = node.properties
@@ -309,16 +339,20 @@ const image = {
     const relative = isInternal(src) && !src.startsWith("/")
     const picture = createDynamicImage(relative ? fromPage(splitURL(src).pathname, target) : src, api, alt)
     if (!picture) {
-      // Left as an <img>: say so when the browser would get a 404 for it.
+      // Left as an <img>. One whose file is read in the background may
+      // only be not read yet; any other miss is a 404, said so.
       const { pathname } = isInternal(src) ? splitURL(src) : {}
-      if (pathname && !readInBackground(pathname, context.config) && !servedTarget(pathname, context)) {
+      if (!pathname || servedTarget(pathname, context)) return SKIP
+      if (!readInBackground(pathname, context.config)) {
         context.config.log?.("warn", `${context.target.source ?? context.target.path}: image ${src} matches no file`)
+        return SKIP
       }
-      return SKIP
-    }
-    if (index === 0 && parent.children.length > 1) {
-      const caption = parent.children.slice(1)
-      parent.children = [h("figure", [picture, h("figcaption", caption)])]
+      // Not read yet, so its size is unknown. A 3:2 box stands in (the
+      // reset sizes an <img> from its attributes, capped at the column),
+      // so the page doesn't jump when the read rewrites it at its own size.
+      if (node.properties.width !== undefined || node.properties.height !== undefined) return SKIP
+      node.properties.width = PENDING_WIDTH
+      node.properties.height = PENDING_HEIGHT
       return SKIP
     }
     return picture
@@ -530,7 +564,7 @@ function trimText(nodes) {
 const skipped = new Set(["pre", "code", "script", "style"])
 
 const writeWalk = createVisitor({
-  block: [internalLink, wikilink, icon, highlight, image, directive, preview, alert],
+  block: [internalLink, wikilink, icon, highlight, captionedImage, image, directive, preview, alert],
   skip: (node) => isElement(node) && skipped.has(node.tagName)
 })
 

package/plugins/images/index.js

@@ -72,23 +72,46 @@ async function readImagePath(source) {
   const hash = digest("sha1", buffer).slice(0, 8)
 
   const ext = path.extname(source.target)
-  const targets = imageSizes.flatMap(size => [...imageExts, ext].map(format => ({
+  const formats = [...imageExts, ext.replace(/^\./, "")]
+  const targets = formats.flatMap(format => imageSizes.map(size => ({
     path: createImagePath({ targetFilePath: source.target, size, ext: format, targetDirectory: "", uuid: hash }),
-    metadata: { derivative: { size, format: format.replace(/^\./, "") } }
+    metadata: { derivative: { size, format } }
   })))
+  const metadata = { hash, width, height, dominant: dominantColor, placeholder }
 
-  return { metadata: { hash, width, height, dominant: dominantColor, placeholder }, targets }
+  if (!isOptimized(source)) return { metadata, targets }
+
+  // Grouped by format in <picture> order (avif, webp, its own), each
+  // smallest first. This list is the one place a derivative's path is
+  // decided: plugins/html/image.js links what it names.
+  const derivatives = targets.map(({ path, metadata }) => ({ path, ...metadata.derivative }))
+  return { metadata: { ...metadata, derivatives }, targets, write: false }
+}
+
+/**
+ * A png or jpeg is never published at full size: its derivatives are
+ * linked everywhere instead, and the original is a virtual target. The
+ * root favicon.png is exempt, because it is linked as it is, as the
+ * site's icon. The other formats are copied through as before; their
+ * derivatives are made but nothing links them yet.
+ * @param {{ path: string, target: string }} source
+ */
+function isOptimized(source) {
+  if (source.path === "favicon.png") return false
+  return /^\.(png|jpe?g)$/.test(path.extname(source.target))
 }
 
 /**
- * An original is copied through. A derivative is resized and converted
- * from its owner's bytes - which is what target.buffer() reads, because
- * votive stored the owner as the derivative's source.
+ * A derivative is resized and converted from its owner's bytes - which
+ * is what target.buffer() reads, because votive stored the owner as the
+ * derivative's source. An original with derivatives is virtual and
+ * writes nothing; any other original is copied through.
  * @type {Votive.ProcessorWrite}
  */
 async function writeImage(target) {
   // The placeholder favicon has no file to read; its bytes are its data.
   if (target.metadata?.favicon) return { data: Buffer.from(target.data, "base64") }
+  if (target.metadata?.derivatives) return
 
   const bytes = target.buffer()
   const recipe = target.metadata?.derivative

package/plugins/markdown/index.js

@@ -16,7 +16,7 @@ import { readFileSync } from "fs"
 import { createHashtagPage, labelFromName, showPages } from "./../../utils.js"
 import { toHast, defaultHandlers } from 'mdast-util-to-hast'
 import { toString as hastToString } from 'hast-util-to-string'
-import getMetadata, { reservedProperties } from "./metadata.js"
+import getMetadata, { imageFromPage, reservedProperties } from "./metadata.js"
 import { isSecretPath, secretRouter, displayPath } from "./../../secretPaths.js"
 import { collectLinks } from "./links.js"
 import { readWalk } from "./readRules.js"
@@ -63,7 +63,9 @@ function readFile(source, { api, config }) {
   if (!metadata.image) {
     const firstImageParagraph = mdast.children.find(child => child.children && child.children[0].type === "image")
     if (firstImageParagraph) {
-      metadata.first_image = firstImageParagraph.children[0].url
+      // A card shows it from another folder's page, so from the root.
+      const folder = path.dirname(targetPath ?? filePath).replace(/^\.$/, "")
+      metadata.first_image = imageFromPage(firstImageParagraph.children[0].url, folder)
     }
   }
 

package/plugins/markdown/metadata.js

@@ -6,6 +6,49 @@ import { displayPath } from "../../secretPaths.js"
 import pathDate from "../../pathDate.js"
 import { coerce, parseFrontmatter, toISODate } from "./frontmatter.js"
 
+/**
+ * An HTML comment, or several in a row with nothing else between them.
+ * It stays in the page, but metadata never reads it (per Sam): a
+ * comment is not a title, a date or a description, and it doesn't take
+ * a block's place in the scan for one.
+ * @param {any} node
+ */
+function isComment(node) {
+  return node.type === "html" && /^\s*(?:<!--[\s\S]*?-->\s*)+$/.test(node.value)
+}
+
+/**
+ * A node's text for metadata: mdastToString with its HTML comments left
+ * out, at any depth. Where a comment sat between two words, the spaces
+ * either side of it close up to one.
+ * @param {any} node
+ * @returns {string}
+ */
+function metadataText(node) {
+  if (isComment(node)) return ""
+  if (!node.children) return mdastToString(node)
+  const text = node.children.map(metadataText).join("")
+  if (!node.children.some(isComment)) return text
+  return text.replace(/[ \t]{2,}/g, " ")
+}
+
+/**
+ * An image the page's text names, as the browser resolves it from the
+ * page: `pic.jpg` and `./pic.jpg` are the page's folder's, `../pic.jpg`
+ * its parent's, `/pic.jpg` the root's. Stored as a path from the root,
+ * the way the html write resolves the same image (`fromPage` in
+ * writeRules.js), because a listing card and `og:image` read it from
+ * pages in other folders. An external url is left as written. (A
+ * frontmatter `image:` is a setting-style path instead: `resolvePath`.)
+ * @param {string} url - as written
+ * @param {string} folder - the page's target folder, project-relative ("" at the root)
+ */
+export function imageFromPage(url, folder) {
+  if (/^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith("//")) return url
+  const base = new URL(folder ? `/${folder.split(path.sep).join("/")}/` : "/", "thismessage://")
+  return decodeURIComponent(new URL(url.replaceAll("#", "%23"), base).pathname)
+}
+
 
 /**
 - menu_item: true | false
@@ -50,7 +93,7 @@ export const reservedProperties = [
  * @param {object} tree
  */
 export function findTitleNode(tree) {
-  const [first] = tree.children.filter(child => child.type !== "yaml")
+  const [first] = tree.children.filter(child => child.type !== "yaml" && !isComment(child))
   if (!first) return null
   if (first.type !== "heading" || first.depth !== 1) return null
   return first
@@ -101,24 +144,29 @@ function markAsTime(paragraph, date) {
  *
  * @param {object} block
  * @param {object} metadata
+ * @param {string} folder - the page's target folder, for a relative image
  * @returns {boolean} whether the block was recognizable data
  */
-function recognizeData(block, metadata) {
+function recognizeData(block, metadata, folder) {
   if (block.type !== "paragraph") return false
-  if (block.children.length !== 1) return false
-
-  const [child] = block.children
+  const children = block.children.filter(child => !isComment(child))
+  const [child] = children
 
   const imageFilled = Boolean(metadata.fm_image || metadata.inferred_image)
 
-  if (child.type === "image") {
+  // An image, alone or with its caption after it on the same line: the
+  // html write makes the pair a <figure> and lifts it whole. The caption
+  // is not a property of the page.
+  if (child?.type === "image") {
     if (imageFilled) return false
-    metadata.inferred_image = child.url
+    metadata.inferred_image = imageFromPage(child.url, folder)
     metadata.inferred_alt_text = child.alt
     return "image"
   }
 
-  const text = mdastToString(block)
+  if (children.length !== 1) return false
+
+  const text = metadataText(block)
 
   // A reference or a listing directive (`/blog/post`, `/blog/**`,
   // `./drafts/*`) is an instruction to the html plugin, not prose - it
@@ -227,16 +275,16 @@ function getMetadata(tree, filePath, targetPath, report = () => {}) {
 
   const titleNode = findTitleNode(tree)
   if (titleNode) {
-    metadata.inferred_title = mdastToString(titleNode) || labelFromName(path.parse(filePath).name)
+    metadata.inferred_title = metadataText(titleNode).trim() || labelFromName(path.parse(filePath).name)
   }
 
   // Everything up to the first block that is not recognizable data is
   // metadata; that first block is where the content begins, and it also
   // supplies the description.
-  const blocks = tree.children.filter(child => child.type !== "yaml" && child !== titleNode)
+  const blocks = tree.children.filter(child => child.type !== "yaml" && child !== titleNode && !isComment(child))
 
   for (const [index, block] of blocks.entries()) {
-    const recognized = recognizeData(block, metadata)
+    const recognized = recognizeData(block, metadata, folder)
     if (recognized === "skip") continue
     if (recognized) {
       markAsNatural(block, recognized)
@@ -251,13 +299,13 @@ function getMetadata(tree, filePath, targetPath, report = () => {}) {
     // markdown, not a paragraph and a rule; it takes a blank line.)
     const next = blocks[index + 1]
     if (!metadata.fm_description && block.type === "paragraph" && next?.type === "thematicBreak") {
-      metadata.declared_description = mdastToString(block)
+      metadata.declared_description = metadataText(block).trim()
       markAsNatural(block, "description")
       markAsNatural(next, "end")
       break
     }
 
-    if (!metadata.fm_description) metadata.inferred_description = mdastToString(block)
+    if (!metadata.fm_description) metadata.inferred_description = metadataText(block).trim()
     break
   }
 

package/stylesheets/DefaultStyles.css

@@ -311,6 +311,7 @@
 			ul {
 				list-style: none;
 				display: flex;
+				flex-wrap: wrap;
 				gap: 2ch;
 			}
 
@@ -438,6 +439,11 @@
 			}
 		}
 
+		/* the page's own image, beside its title, as well as the content's */
+		img {
+			border-radius: var(--borderradius-tight);
+		}
+
 		/* content */
 
 		section#content {
@@ -454,10 +460,6 @@
 				}
 			}
 
-			img {
-				border-radius: var(--borderradius-tight);
-			}
-
 			mark,
 			code {
 				padding: 0.1cap 0.5ch;

package/stylesheets/TypographyStyles.css

@@ -334,15 +334,15 @@
 		&>section {
 			margin-top: 1lh;
 		}
-	}
-
-	/* content */
-	section {
 
-		/* image caption space */
+		/* image caption space: the page's own captioned image, beside its title, as well as the content's */
 		figure {
 			gap: 1lh;
 		}
+	}
+
+	/* content */
+	section {
 
 		/* list spacing */
 		ul,

package/utils.js

@@ -23,26 +23,6 @@ export function createImagePath({ targetFilePath, size, ext, targetDirectory, uu
   })
 }
 
-/**
- * @param {string} targetFilePath
- * @param {string} targetDirectory
- * @param {string} uuid
- */
-export function createImagePaths(targetFilePath, targetDirectory, uuid) {
-  const defaultExt = path.extname(targetFilePath)
-  return [...imageExts, defaultExt].map(ext => {
-    return imageSizes.map(size => {
-      return createImagePath({
-        targetFilePath,
-        size,
-        ext,
-        targetDirectory,
-        uuid
-      })
-    })
-  })
-}
-
 /** @param {string} text */
 export function testURL(text) {
   if (text.match(/^https?:\/\/[\S]+$/)) {