vowel 0.7.1 → 0.7.4

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, mirrorPath } 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).
@@ -527,6 +538,18 @@ function writeFile(target, { settings, api, config }) {
     )
   }
 
+  // The page's markdown mirror (markdown/mirror.js), linked only while
+  // it exists. A tracked read: the page is rebuilt when its mirror is
+  // declared or removed, and not when the mirror is rewritten.
+  const mirror = api.target(mirrorPath(target.path))
+  if (mirror) {
+    treeHead.children.push(h("link", {
+      rel: "alternate",
+      type: "text/markdown",
+      href: "/" + mirror.path.split(path.sep).join("/")
+    }))
+  }
+
   // The page's AT Protocol record, for readers that verify a document
   // against its site: standard.site's convention, so only for a
   // site.standard.document, and only for a page that can be one - it
@@ -545,7 +568,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 +593,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 +634,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 +674,7 @@ function writeFile(target, { settings, api, config }) {
   const treeHeader = h('header', [
     identity,
     treeNav,
-    socialLinksNav(settings)
+    socialLinksNav(settings, api)
   ])
 
 
@@ -699,7 +726,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 +752,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/frontmatter.js

@@ -69,6 +69,7 @@ const EXPECTED = {
   aliases: "strings",
   status: "status",
   html_file: "boolean",
+  markdown_mirror: "boolean",
   rss_item: "boolean",
   sitemap_item: "boolean",
   global_nav_item: "boolean",

package/plugins/markdown/index.js

@@ -16,11 +16,12 @@ 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"
 import { h } from "hastscript"
+import { mirrorStubs, mirrorWriter } from "./mirror.js"
 
 import { styleText } from "node:util"
 
@@ -63,7 +64,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)
     }
   }
 
@@ -231,6 +234,11 @@ function settingsContribution(metadata, filePath, log) {
   if (metadata.fm_slogan !== undefined) {
     log?.("warn", `${filePath}: \`slogan:\` in a settings file does nothing - a slogan belongs to a page, e.g. home.md`)
   }
+  // Mirrors are declared by an enumerator, which sees the root's
+  // settings only.
+  if (metadata.markdown_mirror !== undefined && filePath !== "settings.md") {
+    log?.("warn", `${filePath}: \`markdown_mirror:\` works only in the root settings.md or in a page's frontmatter`)
+  }
   const declared = Object.entries(metadata)
     .filter(([key]) => key.startsWith("fm_") || reservedProperties.includes(key))
   return {
@@ -240,19 +248,6 @@ function settingsContribution(metadata, filePath, log) {
   }
 }
 
-/**
- * The only markdown target vowel produces is settings.md itself (every
- * other .md file is routed to .html), so this passes its source text
- * through untouched - the panel edits the real file, not a rendering of
- * it.
- * @type {Votive.ProcessorWrite}
- */
-function writeMarkdown(target) {
-  return {
-    data: target.data,
-    encoding: "utf-8"
-  }
-}
 
 
 
@@ -489,8 +484,7 @@ const readMarkdown = {
   router,
   createStubs,
   expandStubs,
-  readFile,
-  writeFile: writeMarkdown
+  readFile
 }
 
 
@@ -498,7 +492,7 @@ const readMarkdown = {
 /** @type {Votive.VotivePlugin} */
 const vowelMarkdownPlugin = {
   name: "vowel",
-  processors: [readMarkdown]
+  processors: [readMarkdown, mirrorStubs, mirrorWriter]
 }
 
 export default vowelMarkdownPlugin