vowel 0.7.0-beta.0 → 0.7.1

package/plugins/html/writeRules.js

@@ -4,8 +4,8 @@ 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 { toTitleCase, listPages } from "../../utils.js"
-import { globClasses } from "./editor/directives.js"
+import { showPages, isPageWithoutFile } from "../../utils.js"
+import { globClasses, alertLabel } from "./editor/directives.js"
 import createDynamicImage from "./image.js"
 import { displayPath } from "../../secretPaths.js"
 
@@ -35,27 +35,111 @@ const soleText = (node) => isElement(node) && node.tagName === "p" && node.child
   ? node.children[0].value
   : null
 
+/** A url this site would serve: not another site, not an anchor, not mailto: and the like. */
+const isInternal = (url) => typeof url === "string"
+  && url !== ""
+  && !/^[a-z][a-z0-9+.-]*:/i.test(url)
+  && !url.startsWith("//")
+  && !url.startsWith("#")
+  && !url.startsWith("?")
+
+/**
+ * A url split into its path, decoded, and what follows it (`?query`,
+ * `#anchor`). `##` is a secret segment's marker, not an anchor, so it
+ * is kept in the path.
+ * @param {string} url
+ */
+function splitURL(url) {
+  const masked = url.replaceAll("##", "\0\0")
+  const end = masked.search(/[?#]/)
+  const cut = end === -1 ? url.length : end
+  return { pathname: decodeURIComponent(url.slice(0, cut)), suffix: url.slice(cut) }
+}
+
+/** Where a target is served: a page's pretty url, anything else its path. */
+const urlOf = (found) => found.metadata?.prettyURL ?? "/" + found.path.split(path.sep).join("/")
+
+/**
+ * A path as the browser resolves it from this page: `pic.jpg` on
+ * /blog/post is /blog/pic.jpg. Decoded, from the root. `#` is encoded
+ * on the way in, so a secret segment's `##` stays in the path.
+ * @param {string} pathname - decoded, no query or anchor
+ * @param {any} target - the page
+ */
+function fromPage(pathname, target) {
+  const base = new URL(urlOf(target), "thismessage://")
+  return decodeURIComponent(new URL(pathname.replaceAll("#", "%23"), base).pathname)
+}
+
+/**
+ * The target a browser would get for this url from this page, or null
+ * for a 404: resolved against the page's own url, then looked up as a
+ * file (`/pic.jpg`, `/feed.xml`) or a page (`/about` is about.html). A
+ * tracked read, so a page that appears later rewrites the one linking
+ * to it.
+ * @param {string} pathname - decoded, no query or anchor
+ * @param {{ target: any, api: any }} context
+ */
+function servedTarget(pathname, { target, api }) {
+  const resolved = fromPage(pathname, target)
+  const trimmed = resolved.length > 1 ? resolved.replace(/\/+$/, "") : resolved
+  if (trimmed === "/") return api.target("index.html")
+  const file = trimmed.slice(1).split("/").join(path.sep)
+  return api.target(file) ?? api.target(`${file}.html`)
+}
+
+/** Per config: the extensions its plugins read in the background. */
+const backgroundExtensions = new WeakMap()
+
+/**
+ * Whether a missing path may only be not read *yet*: a file in the
+ * background (format "buffer": images, fonts, documents, video) has no
+ * target until its deferred read, which on a cold build runs after the
+ * first write pass. A miss there is not a 404, and warning about it
+ * flagged 71 of 98 links and images on style-builder whose files were
+ * there. So those go unwarned; the miss is tracked, and the page is
+ * rewritten with the right link when the file is read. A page link or
+ * a wikilink (markdown, read before any write) still warns.
+ * @param {string} pathname
+ * @param {any} config
+ */
+function readInBackground(pathname, config) {
+  if (!backgroundExtensions.has(config)) {
+    const processors = (config.plugins ?? []).flatMap(plugin => plugin.processors ?? [])
+    const extensions = processors.filter(processor => processor.format === "buffer").flatMap(processor => processor.extensions ?? [])
+    backgroundExtensions.set(config, new Set(extensions))
+  }
+  return backgroundExtensions.get(config).has(path.extname(pathname).toLowerCase())
+}
+
 /**
- * `[text](./post.md)` resolves by *source* path to the routed target -
- * which for a secret page is the hashed one, with no second trip
- * through the router. The href may arrive percent-encoded (toHast
- * normalizes non-ASCII). A link to a file that produces no page is the
- * author's to notice, not a reason to stop the build.
+ * A link to this site: `[text](./post.md)`, `../post.md` or
+ * `/blog/post.md` resolves by *source* path to the routed target - for a
+ * secret page the hashed one, with no second trip through the router -
+ * and an asset (`./pic.jpg`) to its path. Anything else (`/about`,
+ * `../tags/x`) is checked as the url it is. A link that goes nowhere
+ * is warned about and left as written: the author's to fix, not a
+ * reason to stop the build. A file read in the background isn't
+ * (readInBackground).
  * @type {import("../markdown/visitor.js").BlockRule}
  */
-const relativeLink = {
-  name: "relativeLink",
-  test: (node) => isElement(node) && node.tagName === "a" && typeof node.properties?.href === "string" && node.properties.href.startsWith("./"),
-  transform: (node, index, parent, { target, api, config }) => {
+const internalLink = {
+  name: "internalLink",
+  test: (node) => isElement(node) && node.tagName === "a" && !hasClass(node, "wikilink") && isInternal(node.properties?.href),
+  transform: (node, index, parent, context) => {
+    const { target, api, config } = context
+    const href = node.properties.href
+    const { pathname, suffix } = splitURL(href)
     // A stub has a source path but no neighbours to resolve against.
-    if (!target.source) return
-    const sourcePath = path.normalize(path.join(path.dirname(target.source), decodeURIComponent(node.properties.href)))
-    const found = api.targetBySource(sourcePath)
+    const sourcePath = target.source && path.extname(pathname)
+      ? path.normalize(pathname.startsWith("/") ? pathname.slice(1) : path.join(path.dirname(target.source), pathname))
+      : null
+    const found = (sourcePath && api.targetBySource(sourcePath)) || servedTarget(pathname, context)
     if (!found) {
-      config.log?.("warn", `${target.source}: link to ${node.properties.href} matches no page`)
+      if (!readInBackground(pathname, config)) config.log?.("warn", `${target.source ?? target.path}: link to ${href} matches no page`)
       return
     }
-    node.properties.href = found.metadata.prettyURL
+    node.properties.href = urlOf(found) + suffix
   }
 }
 
@@ -89,7 +173,8 @@ function resolveNote(name, { api, target }) {
     recursive: true,
     query: { "|": { note_key: key, note_aliases: { "~": key } } }
   }).filter(candidate => (
-    candidate.extension === ".html"
+    candidate.write !== false
+    && candidate.extension === ".html"
     && candidate.path !== target.path
     && (!folderHint || sourceFolder(candidate).endsWith(folderHint))
   ))
@@ -146,6 +231,8 @@ const wikilink = {
     const isFile = /\.[a-z0-9]+$/i.test(name.trim())
     const found = isFile ? resolveFile(name, context) : resolveNote(name, context)
     if (!found) {
+      const { target, config } = context
+      config.log?.("warn", `${target.source ?? target.path}: [[${name}]] matches no page`)
       delete node.properties.href
       return SKIP
     }
@@ -159,7 +246,7 @@ const wikilink = {
 /**
  * `:fa/surfer:` is `fa/surfer.svg` in the project, read through
  * api.target() so a replaced icon restales the page. The same shape as
- * a#logo - an <img> plus --icon-url - so a monochrome SVG can be masked
+ * a#logo - an <img> plus --url-icon - so a monochrome SVG can be masked
  * in currentColor. Missing: the shortcode is put back as written.
  * @type {import("../markdown/visitor.js").BlockRule}
  */
@@ -172,7 +259,7 @@ const icon = {
     if (!found) return { type: "text", value: `:${name}:` }
     const src = `/${found.path}`
     node.properties.src = src
-    node.properties.style = `--icon-url: url("${src}")`
+    node.properties.style = `--url-icon: url("${src}")`
     return SKIP
   }
 }
@@ -212,10 +299,23 @@ const highlight = {
 const image = {
   name: "image",
   test: (node) => isElement(node) && node.tagName === "img" && !hasClass(node, "icon"),
-  transform: (node, index, parent, { api }) => {
+  transform: (node, index, parent, context) => {
+    const { api, target } = context
     const { src, alt } = node.properties
-    const picture = createDynamicImage(src, api, alt)
-    if (!picture) return SKIP
+    // createDynamicImage reads a path from the root; a relative one
+    // (`pic.jpg`, `./pic.jpg`, `../pic.jpg`) is the page's, so resolve it
+    // first. It used to be looked up at the root, miss, and stay a
+    // plain <img>: shown, but never optimised.
+    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.
+      const { pathname } = isInternal(src) ? splitURL(src) : {}
+      if (pathname && !readInBackground(pathname, context.config) && !servedTarget(pathname, context)) {
+        context.config.log?.("warn", `${context.target.source ?? context.target.path}: image ${src} matches no file`)
+      }
+      return SKIP
+    }
     if (index === 0 && parent.children.length > 1) {
       const caption = parent.children.slice(1)
       parent.children = [h("figure", [picture, h("figcaption", caption)])]
@@ -280,7 +380,7 @@ const directive = {
       // Lowercased: every vowel target path is (config.js's router).
       const found = api.target(path.relative("/", path.format(info)).toLowerCase())
       if (!found) return SKIP
-      return makeHeader(found.metadata, found.metadata.prettyURL, api, config)
+      return makeHeader(found.metadata, cardLink(found), api, config, found.source)
     }
 
     const folder = path.relative("/", dir)
@@ -294,20 +394,28 @@ const directive = {
 
     // A relative glob is in source space, where the author named the
     // folder salt and all, so it sees the hidden (secret) pages there;
-    // a published-path glob never does.
+    // a published-path glob never does. A page hidden on purpose
+    // (`status: hidden`) is hidden from both.
     const listing = { folder, recursive, query, orderBy: { property: "date", direction: "desc" }, limit: count ? Number(count) : undefined }
     const targets = relative
-      ? api.targets(listing).filter(page => page.write !== false && page.extension === ".html")
-      : listPages(api, listing)
+      ? api.targets(listing).filter(page => (page.write !== false || isPageWithoutFile(page)) && page.extension === ".html" && page.metadata.fm_status !== "hidden")
+      : showPages(api, listing)
 
     const listClasses = globClasses({ folder, recursive, limit: count, tag, view, properties })
 
     return view === "table"
       ? makeTable(listClasses, properties.length ? properties : ["title"], targets, api)
-      : h("ul", { class: listClasses }, targets.map(found => h("li", makeHeader(found.metadata, found.metadata.prettyURL, api, config))))
+      : h("ul", { class: listClasses }, targets.map(found => h("li", makeHeader(found.metadata, cardLink(found), api, config, found.source))))
   }
 }
 
+/**
+ * Where a card links: the page's url, or nowhere for a page with no
+ * file (`html_file: false`), which is a card and nothing more.
+ * @param {any} found
+ */
+const cardLink = (found) => isPageWithoutFile(found) ? null : found.metadata.prettyURL
+
 /**
  * A relative directive path as the absolute published path it names.
  * The glob's last segment (`*`, `**`) rides along untouched: the
@@ -348,29 +456,81 @@ const preview = {
   }
 }
 
+/** `[!TYPE]` at the very start of an alert, and the spaces after it. */
+const ALERT_MARKER = /^\[!([a-z][\w-]*)\][ \t]*/i
+
+/** A blockquote's first block, if it is a paragraph that opens with `[!TYPE]`. */
+const alertParagraph = (node) => {
+  const first = node.children?.find(isElement)
+  const lead = first?.tagName === "p" ? first.children?.[0] : null
+  return typeof lead?.value === "string" && ALERT_MARKER.test(lead.value) ? first : null
+}
+
 /**
- * A GFM alert: a blockquote whose first line is `[!NOTE]` (or WARNING,
- * DANGER...) becomes an aside with the label as its heading.
+ * A GFM alert, or an Obsidian callout: a blockquote whose first line is
+ * `[!TYPE]`, any word, becomes `<aside class="alert type">` with a
+ * heading. The rest of that line is the heading (`> [!NOTE] How to
+ * render`, inline markdown and all), else the type in sentence case
+ * (alertLabel). Both spellings work: GitHub's, with the text on the
+ * next line - one paragraph, so the marker line is cut off the front of
+ * it - and the marker alone, then a blank `>` line.
  * @type {import("../markdown/visitor.js").BlockRule}
  */
 const alert = {
   name: "alert",
-  test: (node) => isElement(node) && node.tagName === "blockquote"
-    && isElement(node.children?.[1]) && node.children[1].tagName === "p"
-    && node.children[1].children?.length === 1
-    && /^\[!(\w+)\]$/.test(node.children[1].children[0].value ?? ""),
+  test: (node) => isElement(node) && node.tagName === "blockquote" && alertParagraph(node) !== null,
   transform: (node) => {
-    const [, label] = node.children[1].children[0].value.match(/^\[!(\w+)\]$/)
+    const paragraph = alertParagraph(node)
+    const [lead, ...rest] = paragraph.children
+    const marker = ALERT_MARKER.exec(lead.value)
+    const type = marker[1].toLowerCase()
+
+    // The marker's line ends at the first newline: what comes before it
+    // is the title, what comes after is the paragraph.
+    const inline = [{ type: "text", value: lead.value.slice(marker[0].length) }, ...rest]
+    const breakAt = inline.findIndex(child => typeof child.value === "string" && child.value.includes("\n"))
+    const lineEnd = breakAt === -1 ? inline.length : breakAt
+    const split = breakAt === -1 ? null : inline[breakAt].value.indexOf("\n")
+    const title = [
+      ...inline.slice(0, lineEnd),
+      ...(split === null ? [] : [{ type: "text", value: inline[breakAt].value.slice(0, split) }])
+    ]
+    const body = split === null ? [] : [
+      { type: "text", value: inline[breakAt].value.slice(split + 1) },
+      ...inline.slice(breakAt + 1)
+    ]
+
+    const hasTitle = title.some(child => child.type !== "text" || child.value.trim())
+    const heading = h("h2", hasTitle ? trimText(title) : alertLabel(type))
+    const hasBody = body.some(child => child.type !== "text" || child.value.trim())
+
     node.tagName = "aside"
-    node.properties = { class: `alert ${label.toLowerCase()}` }
-    node.children.splice(0, 2, h("h2", toTitleCase(label)))
+    node.properties = { class: `alert ${type}` }
+    const index = node.children.indexOf(paragraph)
+    const kept = hasBody ? [{ ...paragraph, children: trimText(body) }] : []
+    node.children = [heading, ...node.children.slice(0, index).filter(isElement), ...kept, ...node.children.slice(index + 1)]
   }
 }
 
+/**
+ * Inline nodes with the whitespace trimmed from both ends of the run.
+ * @param {any[]} nodes
+ */
+function trimText(nodes) {
+  const last = nodes.length - 1
+  return nodes
+    .map((child, index) => {
+      if (typeof child.value !== "string" || child.type !== "text") return child
+      const start = index === 0 ? child.value.trimStart() : child.value
+      return { ...child, value: index === last ? start.trimEnd() : start }
+    })
+    .filter(child => child.type !== "text" || child.value !== "")
+}
+
 const skipped = new Set(["pre", "code", "script", "style"])
 
 const writeWalk = createVisitor({
-  block: [relativeLink, wikilink, icon, highlight, image, directive, preview, alert],
+  block: [internalLink, wikilink, icon, highlight, image, directive, preview, alert],
   skip: (node) => isElement(node) && skipped.has(node.tagName)
 })
 

package/plugins/images/index.js

@@ -1,4 +1,5 @@
 import { hash as digest } from "node:crypto"
+import { readFileSync } from "node:fs"
 import path from "node:path"
 import sharp from 'sharp'
 import { createImagePath, imageSizes, imageExts } from "./../../utils.js"
@@ -37,6 +38,18 @@ function hex(channel) {
   return Math.round(channel).toString(16).padStart(2, "0")
 }
 
+/**
+ * A blurry stand-in for the image while it loads, inlined in the page:
+ * 16 px on its long side, low-quality WebP, a data URI of roughly
+ * 150-300 bytes. The browser smooths it as it scales up. Done here
+ * rather than with lqip-modern, which wraps these same sharp calls.
+ * @param {import("sharp").Sharp} image
+ */
+async function placeholderURI(image) {
+  const bytes = await image.clone().resize(16, 16, { fit: "inside" }).webp({ quality: 20 }).toBuffer()
+  return `data:image/webp;base64,${bytes.toString("base64")}`
+}
+
 /**
  * Runs deferred, with the bytes (buffer format), so this is where an
  * image is looked at. Dimensions go on <img width height> so the browser
@@ -51,8 +64,11 @@ function hex(channel) {
 async function readImagePath(source) {
   const buffer = source.buffer()
   const image = sharp(buffer)
-  const [{ width, height }, { dominant }] = await Promise.all([image.metadata(), image.stats()])
+  const [{ width, height, hasAlpha }, { dominant }] = await Promise.all([image.metadata(), image.stats()])
   const dominantColor = dominant ? `#${hex(dominant.r)}${hex(dominant.g)}${hex(dominant.b)}` : undefined
+  // Not behind an image with transparency: the page has no script to take
+  // it away once the image loads, so it would show through.
+  const placeholder = hasAlpha ? undefined : await placeholderURI(image)
   const hash = digest("sha1", buffer).slice(0, 8)
 
   const ext = path.extname(source.target)
@@ -61,7 +77,7 @@ async function readImagePath(source) {
     metadata: { derivative: { size, format: format.replace(/^\./, "") } }
   })))
 
-  return { metadata: { hash, width, height, dominant: dominantColor }, targets }
+  return { metadata: { hash, width, height, dominant: dominantColor, placeholder }, targets }
 }
 
 /**
@@ -71,6 +87,9 @@ async function readImagePath(source) {
  * @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") }
+
   const bytes = target.buffer()
   const recipe = target.metadata?.derivative
   if (!recipe) return { data: bytes }
@@ -89,10 +108,29 @@ const imagesProcessor = {
   writeFile: writeImage
 }
 
+/**
+ * Every site has Vowel's mark as a placeholder favicon,
+ * `favicon-placeholder.png`, published always and linked only when the
+ * site has no `icon` and no `favicon.png` of its own (the html plugin).
+ * A stub of its own source type (`.favicon`, which nothing else uses)
+ * read as base64 text, so it is read with the pages rather than with
+ * the images in the background. A write is matched on the target's
+ * extension, so writeImage writes it, from that text.
+ * @type {Votive.VotiveProcessor}
+ */
+const faviconProcessor = {
+  extensions: [".favicon"],
+  format: "text",
+  router: ({ name, dir }) => ({ name, dir, ext: ".png" }),
+  createStubs: () => [{ path: "favicon-placeholder.favicon" }],
+  expandStubs: () => ({ text: readFileSync(path.join(import.meta.dirname, "favicon.png")).toString("base64") }),
+  readFile: (source) => ({ data: source.text, metadata: { favicon: true } })
+}
+
 /** @type {Votive.VotivePlugin} */
 const vowelImagesPlugin = {
   name: "vowel-images",
-  processors: [imagesProcessor]
+  processors: [imagesProcessor, faviconProcessor]
 }
 
 export default vowelImagesPlugin

package/plugins/markdown/colorScheme.js

@@ -4,16 +4,70 @@ import { fallbackColors } from "./brandColors.js"
 /**
  * Ten shades per role, named `01` (darkest) to `10` (lightest) in
  * colorhorse's own darkest-first order. DefaultStyles.css reads them
- * that way round: `light-dark(var(--primary-10), var(--primary-01))`
+ * that way round: `light-dark(var(--color-primary-10), var(--color-primary-01))`
  * is the body background. tests/colorScheme.js pins the order.
  */
 const shadeCount = 10
 
+/**
+ * The `theme` keys that tune the scheme, each one colorhorse option, all
+ * numbers from 0 to 1. The defaults are vowel's, set before these were
+ * settings; `contrast` 0 is colorhorse's, evenly spread shades.
+ */
+const schemeSettings = [
+  { key: "darkest-shade", option: "minLightness", default: 0.3 },
+  { key: "lightest-shade", option: "maxLightness", default: 0.99 },
+  { key: "min-saturation", option: "minChroma", default: 0.2 },
+  { key: "contrast", option: "contrast", default: 0 }
+]
+
+const defaultOptions = Object.fromEntries(schemeSettings.map(setting => [setting.option, setting.default]))
+
 /** @param {number} index */
 function shadeName(index) {
   return String(index).padStart(2, "0")
 }
 
+/** @param {unknown} value */
+function isFraction(value) {
+  return typeof value === "number" && value >= 0 && value <= 1
+}
+
+/**
+ * The part of a theme the colors sheet is generated from, as stub
+ * params: the sheet re-expands when one of these changes, and only then.
+ * @param {Record<string, unknown>} theme - a resolved theme's config
+ */
+function colorParams(theme) {
+  const settings = schemeSettings.map(setting => [setting.key, theme[setting.key] ?? null])
+  return { colors: theme.colors ?? null, ...Object.fromEntries(settings) }
+}
+
+/**
+ * colorhorse's options from a theme's settings. A value that is not a
+ * number from 0 to 1 is reported and left at its default, rather than
+ * costing the site its colors: colorhorse throws for `contrast` alone,
+ * and turns the rest into ramps nobody asked for.
+ * @param {Record<string, unknown>} theme
+ * @param {(error: Error) => void} onError
+ */
+function schemeOptions(theme, onError) {
+  const entries = schemeSettings.map(setting => {
+    const value = theme[setting.key]
+    if (value === undefined || value === null) return [setting.option, setting.default]
+    if (isFraction(value)) return [setting.option, value]
+    onError(new Error(`ignoring theme.${setting.key} - expected a number from 0 to 1, got ${JSON.stringify(value)}`))
+    return [setting.option, setting.default]
+  })
+  const options = Object.fromEntries(entries)
+
+  // Reversed, colorhorse still answers, with a ramp whose "darkest"
+  // shade is the lighter one.
+  if (options.minLightness < options.maxLightness) return options
+  onError(new Error(`ignoring theme.darkest-shade and theme.lightest-shade - the darkest shade (${options.minLightness}) must be below the lightest (${options.maxLightness})`))
+  return { ...options, minLightness: defaultOptions.minLightness, maxLightness: defaultOptions.maxLightness }
+}
+
 /**
  * Builds the `:root` block for a theme's `colors` seed pair, falling
  * back to Vowel's brand colors when a site hasn't configured any.
@@ -23,20 +77,21 @@ function shadeName(index) {
  * messages are specific ("colorOne has a chroma of zero...") and are
  * left to surface as they are.
  * @param {unknown} colors - a theme setting's `colors`
+ * @param {object} [options] - colorhorse's, already checked (schemeOptions)
  * @returns {string}
  */
-function colorSchemeCSS(colors) {
-  if (colors === undefined || colors === null) return colorSchemeCSS(fallbackColors)
+function colorSchemeCSS(colors, options = defaultOptions) {
+  if (colors === undefined || colors === null) return colorSchemeCSS(fallbackColors, options)
 
   if (!Array.isArray(colors) || colors.length !== 2) {
     throw new Error(`theme.colors must be an array of two "#rrggbb" colors, got ${JSON.stringify(colors)}`)
   }
 
   const [colorOne, colorTwo] = colors
-  const scheme = getScheme(colorOne, colorTwo, { shadeCount, minLightness: 0.3, maxLightness: 0.99, minChroma: 0.2 })
+  const scheme = getScheme(colorOne, colorTwo, { ...options, shadeCount })
 
   const declarations = Object.entries(scheme).flatMap(([role, ramp]) => (
-    ramp.map((color, index) => `  --${role}-${shadeName(index + 1)}: ${color};`)
+    ramp.map((color, index) => `  --color-${role}-${shadeName(index + 1)}: ${color};`)
   ))
 
   return `:root {\n${declarations.join("\n")}\n}\n`
@@ -45,20 +100,21 @@ function colorSchemeCSS(colors) {
 /**
  * The build-facing entry point: always returns a usable `:root` block.
  * Invalid configuration is reported through `onError` and then falls
- * back to the brand colors, so a typo in settings.md leaves the site
- * styled instead of stripping every color variable out from under
- * DefaultStyles.css.
- * @param {unknown} colors
+ * back - unusable colors to the brand colors, a bad setting to its
+ * default - so a typo in settings.md leaves the site styled instead of
+ * stripping every color variable out from under DefaultStyles.css.
+ * @param {Record<string, unknown>} theme - colorParams' shape
  * @param {(error: Error) => void} onError
  * @returns {string}
  */
-function themeColorSchemeCSS(colors, onError) {
+function themeColorSchemeCSS(theme, onError) {
+  const options = schemeOptions(theme, onError)
   try {
-    return colorSchemeCSS(colors)
+    return colorSchemeCSS(theme.colors, options)
   } catch (error) {
-    onError(error)
-    return colorSchemeCSS(fallbackColors)
+    onError(new Error(`ignoring theme.colors - ${error.message}`))
+    return colorSchemeCSS(fallbackColors, options)
   }
 }
 
-export { colorSchemeCSS, themeColorSchemeCSS, fallbackColors }
+export { colorSchemeCSS, themeColorSchemeCSS, colorParams, fallbackColors }

package/plugins/markdown/frontmatter.js

@@ -33,9 +33,18 @@ import extractDate from "../../extractDate.js"
  */
 
 /**
- * @typedef {"string" | "date" | "path" | "boolean" | "number" | "strings" | "theme" | "links" | "publication" | "object"} Shape
+ * @typedef {"string" | "date" | "path" | "paths" | "boolean" | "number" | "strings" | "theme" | "links" | "publication" | "object" | "status"} Shape
  */
 
+/**
+ * A page's visibility. `published` is the default. `hidden` writes the
+ * page but lists it nowhere - no menu, listing, sitemap, feed or record.
+ * `draft` skips the page entirely.
+ * `deleted` skips it too, and tells `atproto-publish` to delete its
+ * record.
+ */
+const STATUSES = ["published", "draft", "hidden", "deleted"]
+
 /**
  * The keys vowel reads and the shape each one has. Everything else in a
  * frontmatter block is the author's own data.
@@ -45,7 +54,7 @@ const EXPECTED = {
   title: "string",
   breadcrumb: "string",
   description: "string",
-  tagline: "string",
+  slogan: "string",
   name: "string",
   author: "string",
   domain: "string",
@@ -54,20 +63,23 @@ const EXPECTED = {
   logo: "path",
   wordmark: "path",
   icon: "path",
+  fallback_image: "path",
+  styles: "paths",
   tags: "strings",
   aliases: "strings",
-  published: "boolean",
+  status: "status",
   html_file: "boolean",
   rss_item: "boolean",
   sitemap_item: "boolean",
-  global_menu_item: "boolean",
-  local_menu_item: "boolean",
+  global_nav_item: "boolean",
+  local_nav_item: "boolean",
   feed_limit: "number",
   theme: "theme",
   social_links: "links",
   robots: "object",
   atproto_did: "string",
   atproto_lexicon: "string",
+  atproto_content: "string",
   atproto_publication: "publication",
   cloudflare_project: "string",
   atproto_pds: "string"
@@ -132,6 +144,12 @@ function coerceOne(shape, value, folder) {
     if (inner) return { value: resolvePath(inner, folder), problem: `expected a path, got ${Array.isArray(value) ? "a list" : "an object"}; using "${inner}"` }
     return { value: undefined, problem: `expected a path, got ${JSON.stringify(value)}` }
   }
+  if (shape === "paths") {
+    const values = Array.isArray(value) ? value : [value]
+    const kept = values.filter(item => typeof item === "string" && item.trim()).map(item => resolvePath(item, folder))
+    if (!kept.length) return { value: undefined, problem: `expected a path or a list of paths, got ${JSON.stringify(value)}` }
+    return kept.length === values.length ? { value: kept } : { value: kept, problem: "expected a list of paths; dropped what was not" }
+  }
   if (shape === "boolean") {
     if (typeof value === "boolean") return { value }
     const word = String(value).trim().toLowerCase()
@@ -179,6 +197,14 @@ function coerceOne(shape, value, folder) {
     ]
     return wrong.length ? { value: kept, problem: `${wrong.join(", ")}; dropped` } : { value: kept }
   }
+  if (shape === "status") {
+    // One of vowel's four controls the page. Anything else is the
+    // author's own `status` - a digital garden's "evergreen" or
+    // "growing" - kept as written, the page published as usual.
+    const word = typeof value === "string" ? value.trim().toLowerCase() : undefined
+    if (STATUSES.includes(word)) return { value: word }
+    return { value }
+  }
   if (shape === "object") {
     if (isPlainObject(value)) return { value }
     return { value: undefined, problem: `expected an object, got ${JSON.stringify(value)}` }
@@ -250,4 +276,4 @@ function asContent(tree, node) {
   return undefined
 }
 
-export { EXPECTED, coerce, parseFrontmatter, resolvePath, toISODate }
+export { EXPECTED, STATUSES, coerce, parseFrontmatter, resolvePath, toISODate }