vowel 0.7.3 → 0.7.5

package/bin.js

@@ -281,12 +281,24 @@ async function main() {
     return
   }
 
-  // `vowel export <folder>`: the export command (plugins/export), spelled
-  // as a word rather than --command/--payload.
-  if (args._?.[0] === "export") {
+  // `vowel export <folder>` and `vowel check`: two commands spelled as
+  // words rather than --command/--payload. Any other word is a mistake,
+  // said so: it used to be ignored and start the preview, which never
+  // exits - under CI, a job that hung until it timed out.
+  const word = args._?.[0]
+  if (word === "export") {
     await runCLICommand("export", JSON.stringify({ path: args._[1] }))
     return
   }
+  if (word === "check") {
+    await runCLICommand("check")
+    return
+  }
+  if (word !== undefined) {
+    console.error(`vowel: unknown command "${word}". The words are \`vowel export <folder>\` and \`vowel check\`; any other command is \`vowel --command <name>\`.`)
+    process.exitCode = 1
+    return
+  }
 
   // A site is a folder with a settings.md; the wizard writes one. Not "no
   // database yet", which was also true of every site cloned onto a new

package/config.js

@@ -18,6 +18,7 @@ import vowelPublishPlugin from "./plugins/publish/index.js"
 import vowelURLsPlugin from "./plugins/urls/index.js"
 import vowelSecretPagesPlugin from "./plugins/secret-pages/index.js"
 import vowelExportPlugin from "./plugins/export/index.js"
+import vowelCheckPlugin from "./plugins/check/index.js"
 
 /** @import {VotiveConfig} from "votive" */
 
@@ -54,6 +55,7 @@ const defaultPlugins = [
   vowelAssetsPlugin,
   vowelDeployCloudflarePlugin,
   vowelExportPlugin,
+  vowelCheckPlugin,
   vowelURLsPlugin,
   vowelAtprotoPlugin,
   vowelPublishPlugin,

package/index.js

@@ -12,15 +12,10 @@ import { createConfig } from "./config.js"
  *   differ from the one requested; `close()` releases the watchers and the
  *   listener, which a host serving more than one project over a session
  *   needs before opening the next one.
- *
- * The dev server prints each secret page's url as it first sees it
- * (plugins/secret-pages), which is how an author finds them. Only here:
- * a build that deploys or publishes may be logged somewhere public.
- * Pass `announceSecretPages: false` to turn it off.
  */
 async function init(options = {}) {
   const { sourceFolder, ...overrides } = options
-  const config = createConfig(sourceFolder, { announceSecretPages: true, ...overrides })
+  const config = createConfig(sourceFolder, overrides)
   return startServer(config)
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vowel",
   "type": "module",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "engines": {
     "node": ">=26"
   },

package/plugins/assets/index.js

@@ -28,22 +28,29 @@ const DEFAULT_SIZE_LIMIT = 25 * 1024 * 1024
 /** @param {number} bytes */
 const megabytes = (bytes) => `${(bytes / (1024 * 1024)).toFixed(1)} MB`
 
+/** @param {Votive.VotiveConfig} config */
+const sizeLimit = (config) => Number(config.assetSizeLimit) || DEFAULT_SIZE_LIMIT
+
 /**
  * @type {Votive.ProcessorRead}
  */
 function readAsset(source, { config }) {
-  const limit = Number(config.assetSizeLimit) || DEFAULT_SIZE_LIMIT
   const { size } = statSync(path.join(config.sourceFolder, source.path))
-  if (size <= limit) return { metadata: { size } }
-
-  config.log?.("error", `${source.path} is ${megabytes(size)}; files over ${megabytes(limit)} are not published (Cloudflare Pages refuses them). Host it elsewhere and link to it.`)
+  if (size <= sizeLimit(config)) return { metadata: { size } }
   return { metadata: { size, oversized: true }, write: false }
 }
 
-/** @type {Votive.ProcessorWrite} */
-function writeAsset(target) {
-  if (target.metadata?.oversized) return undefined
-  return { data: target.buffer() }
+/**
+ * An oversized file is reported here, not at its read: a buffer read
+ * is cached, and a cached read never calls the hook again, so a check
+ * on a warm cache (`vowel check`) would never have heard of it. Every
+ * fresh build writes every target.
+ * @type {Votive.ProcessorWrite}
+ */
+function writeAsset(target, { config }) {
+  if (!target.metadata?.oversized) return { data: target.buffer() }
+  config.log?.("error", `${target.source ?? target.path} is ${megabytes(target.metadata.size)}; files over ${megabytes(sizeLimit(config))} are not published (Cloudflare Pages refuses them). Host it elsewhere and link to it.`)
+  return undefined
 }
 
 /** @type {Votive.VotiveProcessor} */

package/plugins/atproto/body.js

@@ -5,6 +5,7 @@ import { gfmFootnoteToMarkdown } from "mdast-util-gfm-footnote"
 import { gfmTaskListItemToMarkdown } from "mdast-util-gfm-task-list-item"
 import { toText } from "hast-util-to-text"
 import { emojiFor } from "../markdown/emoji.js"
+import { alertLabel } from "../html/editor/directives.js"
 
 /**
  * A page's body as a record carries it, from the rendered
@@ -17,7 +18,8 @@ import { emojiFor } from "../markdown/emoji.js"
  *   and footnotes vowel itself reads. Links and images are absolute; an
  *   image links to its copy on the site. An icon is its emoji, or its
  *   shortcode as text. A listing is a list of links. A hashtag is a link
- *   whose text keeps its `#`. No title: it is outside the section.
+ *   whose text keeps its `#`. An alert is GFM's (`> [!NOTE]`). No
+ *   title: it is outside the section.
  * - **Rich text** (`richTextBody`), for a `text` field with `facets`
  *   beside it: plain text, and a facet for each link, hashtag and mark
  *   the lexicon has a feature for. The rest is dropped, images included.
@@ -181,7 +183,8 @@ function block(node, base) {
   if (/^h[1-6]$/.test(tag)) return [{ type: "heading", depth: Number(tag[1]), children: trimPhrasing(phrasing(node.children ?? [], base)) }]
   if (tag === "hr") return [{ type: "thematicBreak" }]
   if (tag === "picture") return [paragraph([node], base)]
-  if (tag === "blockquote" || hasClass(node, "markdown-alert")) return [{ type: "blockquote", children: blocks(node.children ?? [], base) }]
+  if (tag === "aside" && hasClass(node, "alert")) return [alert(node, base)]
+  if (tag === "blockquote") return [{ type: "blockquote", children: blocks(node.children ?? [], base) }]
   if (tag === "pre") {
     const code = (node.children ?? []).find(child => is(child, "code")) ?? node
     const language = classes(code).find(name => name.startsWith("language-"))?.slice("language-".length)
@@ -193,6 +196,30 @@ function block(node, base) {
   return blocks(node.children ?? [], base)
 }
 
+/**
+ * An alert, `<aside class="alert note">` with its heading first, back in
+ * GFM's form: `> [!NOTE]`, then the text on the next line. A heading the
+ * author wrote stays on the marker's line (`> [!NOTE] How to render`,
+ * Obsidian's title, which vowel reads too); the default one, the type in
+ * sentence case, is left off. The marker is raw `html` so that it is
+ * not escaped as a link reference.
+ * @param {any} node
+ * @param {string} base
+ */
+function alert(node, base) {
+  const type = classes(node).find(name => name !== "alert") ?? "note"
+  const [first, ...rest] = (node.children ?? []).filter(child => child.type === "element")
+  const hasHeading = /^h[1-6]$/.test(first?.tagName ?? "")
+  const title = hasHeading && toText(first).trim() !== alertLabel(type) ? trimPhrasing(phrasing(first.children ?? [], base)) : []
+  const marker = [{ type: "html", value: `[!${type.toUpperCase()}]` }, ...(title.length ? [{ type: "text", value: " " }, ...title] : [])]
+  const body = blocks(hasHeading ? rest : [first, ...rest].filter(child => child), base)
+  const [lead, ...after] = body
+  const children = lead?.type === "paragraph"
+    ? [{ ...lead, children: [...marker, { type: "text", value: "\n" }, ...lead.children] }, ...after]
+    : [{ type: "paragraph", children: marker }, ...body]
+  return { type: "blockquote", children }
+}
+
 /** @param {any} node @param {string} base */
 function list(node, base) {
   const items = (node.children ?? []).filter(child => is(child, "li"))

package/plugins/check/index.js

@@ -0,0 +1,98 @@
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import votive from "votive"
+
+/**
+ * `vowel check` (or `vowel --command check`): builds the site once and
+ * lists every warning and error the build logged, each at its place in
+ * the source (`home.md:6:15: link to /nowhere matches no page`), then
+ * fails when there were any. A person sees what to fix; an agent or CI
+ * gets an exit code. Warnings fail it too: a link that would 404 is only
+ * a warning, and it is what a check is for.
+ *
+ * Every warning is already reported through `config.log`, so the check
+ * is a log that collects rather than prints. The build is a fresh one -
+ * an in-memory database and a throwaway output folder - because a warm
+ * build reads only what changed, and the warnings of everything else
+ * would never be said. The buffer cache is shared, so images are not
+ * decoded again; nothing a buffer read decides is reported at the read
+ * (plugins/assets reports a file that is too large at its write).
+ *
+ * @param {unknown} payload
+ * @param {{ config: import("votive").VotiveConfig, notify: (message: object) => void }} context
+ */
+async function check(payload, { config, notify }) {
+  notify({ status: "progress", message: "Checking..." })
+
+  const problems = new Map()
+  /** @type {(level: "error" | "warn" | "info", message: string) => void} */
+  const log = (level, message) => {
+    if (level === "info") return
+    // A page written again in the follow-up build warns again.
+    problems.set(`${level} ${message}`, { level, message })
+  }
+
+  const targetFolder = await mkdtemp(path.join(tmpdir(), "vowel-check-"))
+  try {
+    const site = await votive({ ...config, log, targetFolder, databasePath: ":memory:" })
+    try {
+      await (await site.build()).deferred
+    } finally {
+      await site.close()
+    }
+  } finally {
+    await rm(targetFolder, { recursive: true, force: true })
+  }
+
+  const sorted = [...problems.values()].sort(bySource)
+  sorted.forEach(({ level, message }) => notify({ status: "progress", message: `${level === "error" ? "error" : "warning"}  ${message}` }))
+
+  const errors = sorted.filter(({ level }) => level === "error").length
+  const warnings = sorted.length - errors
+  if (!sorted.length) {
+    notify({ status: "done", message: "No problems found." })
+    return undefined
+  }
+  throw new Error(`${count(errors, "error")} and ${count(warnings, "warning")}`)
+}
+
+/**
+ * @param {number} n
+ * @param {string} noun
+ */
+const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`
+
+/**
+ * Where a message says it is: `home.md:6:15: …`, `settings.md: …`, or,
+ * for a message that names no file first, the message itself.
+ * @param {string} message
+ */
+function sourceOf(message) {
+  const match = /^(.+?)(?::(\d+))?(?::(\d+))?: /.exec(message)
+  if (!match) return { file: message, line: 0, column: 0 }
+  return { file: match[1], line: Number(match[2] ?? 0), column: Number(match[3] ?? 0) }
+}
+
+/**
+ * By file, then line and column, so a file's problems read top to
+ * bottom and the order doesn't depend on which page was written first.
+ * @param {{ message: string }} a
+ * @param {{ message: string }} b
+ */
+function bySource(a, b) {
+  const left = sourceOf(a.message)
+  const right = sourceOf(b.message)
+  if (left.file !== right.file) return left.file < right.file ? -1 : 1
+  if (left.line !== right.line) return left.line - right.line
+  return left.column - right.column
+}
+
+/** @type {import("votive").VotivePlugin} */
+const vowelCheckPlugin = {
+  name: "vowel-check",
+  commands: { check }
+}
+
+export default vowelCheckPlugin
+export { check }

package/plugins/html/index.js

@@ -13,7 +13,7 @@ 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, imageSizes } 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'
@@ -388,7 +388,7 @@ function writeFile(target, { settings, api, config }) {
     .filter(entry => !external.includes(entry))
     .map(entry => ({ entry, sheet: entry.replace(/^\/+/, "").split("/").join(path.sep) }))
   const missing = named.filter(({ sheet }) => !api.target(sheet))
-  missing.forEach(({ entry }) => config.log?.("warn", `${target.path}: styles names ${entry}, which isn't in the project`))
+  missing.forEach(({ entry }) => config.log?.("warn", `${target.source ?? target.path}: styles names ${entry}, which isn't in the project`))
   const namedSheets = named.filter(({ sheet }) => !missing.some(gone => gone.sheet === sheet)).map(({ sheet }) => sheet)
 
   // A stub stylesheet has a source path like any other source, so the
@@ -538,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
@@ -776,8 +788,9 @@ function writeFile(target, { settings, api, config }) {
     ]
   )
 
-  try {
-    
+  // Not caught here: a throw is votive's to report (attempt.js), as one
+  // error line naming the page, and the page stays stale. Caught and
+  // logged here, it was marked fresh, and the old page stayed up.
   const data = unified()
     .use(rehypePresetMinify)
     .use(rehypeStringify)
@@ -786,10 +799,6 @@ function writeFile(target, { settings, api, config }) {
   return {
     data
   }
-
-  } catch(e) {
-    console.log({ tree, target, e })
-  }
 }
 
 /**

package/plugins/html/writeRules.js

@@ -4,11 +4,20 @@ 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, imageSizes } from "../../utils.js"
+import { showPages, isPageWithoutFile, imageSizes, sourceLocation } from "../../utils.js"
 import { globClasses, alertLabel } from "./editor/directives.js"
 import createDynamicImage, { derivativeURL } from "./image.js"
 import { displayPath } from "../../secretPaths.js"
 
+/**
+ * The page's source, at the node a warning is about (utils.js). Nodes
+ * parsed from the page carry their line and column; a node the build
+ * made does not, and the warning names the file alone.
+ * @param {any} node
+ * @param {any} target
+ */
+const at = (node, target) => sourceLocation(target.source ?? target.path, node?.position?.start)
+
 /**
  * The write walk: one pass over a page's hast for everything that
  * renders against other targets, settings or the url store - which is
@@ -136,7 +145,7 @@ const internalLink = {
       : null
     const found = (sourcePath && api.targetBySource(sourcePath)) || servedTarget(pathname, context)
     if (!found) {
-      if (!readInBackground(pathname, config)) config.log?.("warn", `${target.source ?? target.path}: link to ${href} matches no page`)
+      if (!readInBackground(pathname, config)) config.log?.("warn", `${at(node, target)}: link to ${href} matches no page`)
       return
     }
     // A link to a png or jpeg opens its largest derivative: the
@@ -234,7 +243,7 @@ const wikilink = {
     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`)
+      config.log?.("warn", `${at(node, target)}: [[${name}]] matches no page`)
       delete node.properties.href
       return SKIP
     }
@@ -344,7 +353,7 @@ const image = {
       const { pathname } = isInternal(src) ? splitURL(src) : {}
       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`)
+        context.config.log?.("warn", `${at(node, context.target)}: image ${src} matches no file`)
         return SKIP
       }
       // Not read yet, so its size is unknown. A 3:2 box stands in (the
@@ -384,7 +393,7 @@ const directive = {
     const relative = !value.startsWith("/")
 
     if (!relative && value.includes("##")) {
-      config.log?.("error", `${target.source ?? target.path}: a listing by published path cannot name a secret folder (${value}); write it relative to this file, as \`./…\``)
+      config.log?.("error", `${at(node, target)}: a listing by published path cannot name a secret folder (${value}); write it relative to this file, as \`./…\``)
       return []
     }
 
@@ -398,7 +407,7 @@ const directive = {
       ? routeRelative(pathPart, target, config)
       : pathPart
     if (routed === undefined) {
-      config.log?.("warn", `${target.path}: ${value} cannot be resolved from a page with no source file`)
+      config.log?.("warn", `${at(node, target)}: ${value} cannot be resolved from a page with no source file`)
       return SKIP
     }
     const url = new URL(routed, "thismessage://")

package/plugins/markdown/frontmatter.js

@@ -1,7 +1,8 @@
-import yaml from "yaml"
+import yaml, { LineCounter } from "yaml"
 import path from "node:path"
 import { fromMarkdown } from "mdast-util-from-markdown"
 import extractDate from "../../extractDate.js"
+import { sourceLocation } from "../../utils.js"
 
 /**
  * How vowel handles a frontmatter block. Stated once, here, per Sam
@@ -69,6 +70,7 @@ const EXPECTED = {
   aliases: "strings",
   status: "status",
   html_file: "boolean",
+  markdown_mirror: "boolean",
   rss_item: "boolean",
   sitemap_item: "boolean",
   global_nav_item: "boolean",
@@ -219,8 +221,10 @@ function coerceOne(shape, value, folder) {
  * @param {string} filePath - project-relative, for the error line
  * @param {string} folder - the folder paths resolve against
  * @param {(message: string) => void} report
+ * @param {Record<string, Point>} [points] - each key's place in the file,
+ *   so the error line names it
  */
-function coerce(frontmatter, filePath, folder, report) {
+function coerce(frontmatter, filePath, folder, report, points = {}) {
   const result = {}
   for (const key in frontmatter) {
     const shape = EXPECTED[key]
@@ -229,39 +233,87 @@ function coerce(frontmatter, filePath, folder, report) {
       continue
     }
     const { value, problem } = coerceOne(shape, frontmatter[key], folder)
-    if (problem) report(`${filePath}: \`${key}:\` ${problem}${value === undefined ? "; ignoring it" : ""}`)
+    if (problem) report(`${sourceLocation(filePath, points[key])}: \`${key}:\` ${problem}${value === undefined ? "; ignoring it" : ""}`)
     if (value !== undefined) result[key] = value
   }
   return result
 }
 
+/** @typedef {{ line: number, column: number }} Point */
+
+/**
+ * A point in the YAML, as a point in the file: the block's first line
+ * is the one after its opening `---`.
+ * @param {object} node - the `yaml` node
+ * @param {{ line: number, col: number }} [linePos] - yaml's, 1-based
+ * @returns {Point | undefined}
+ */
+function filePoint(node, linePos) {
+  const start = node.position?.start
+  if (!start || !linePos) return undefined
+  return { line: start.line + linePos.line, column: linePos.col }
+}
+
+/**
+ * Where each top-level key is written, in the file.
+ * @param {object} node - the `yaml` node
+ * @param {import("yaml").Document} document
+ * @param {LineCounter} lines
+ * @returns {Record<string, Point>}
+ */
+function keyPoints(node, document, lines) {
+  const items = yaml.isMap(document.contents) ? document.contents.items : []
+  const located = items
+    .filter(item => yaml.isScalar(item.key) && item.key.range)
+    .map(item => [String(item.key.value), filePoint(node, lines.linePos(item.key.range[0]))])
+  return Object.fromEntries(located)
+}
+
+/**
+ * Where each top-level key of a frontmatter block is written, for a
+ * warning about a key that is read somewhere else (a settings.md's
+ * `title:`). Parses the block again, so it is for the rare warning,
+ * not for every read.
+ * @param {object} node - the `yaml` node
+ * @returns {Record<string, Point>}
+ */
+function frontmatterPoints(node) {
+  const lines = new LineCounter()
+  const document = yaml.parseDocument(node.value, { lineCounter: lines, logLevel: "error" })
+  return keyPoints(node, document, lines)
+}
+
 /**
- * Parses a frontmatter node. On a parse error the node is replaced in
- * the tree by the markdown it would have been - rule 1 above - and
- * nothing is returned.
+ * Parses a frontmatter node, with each key's place in the file. On a
+ * parse error the node is replaced in the tree by the markdown it would
+ * have been - rule 1 above - and nothing is returned.
  * @param {object} tree - the mdast root
  * @param {object} node - its `yaml` child
  * @param {string} filePath
  * @param {(message: string) => void} report
- * @returns {Record<string, unknown> | undefined}
+ * @returns {{ values: Record<string, unknown>, points: Record<string, Point> } | undefined}
  */
 function parseFrontmatter(tree, node, filePath, report) {
-  try {
-    // logLevel "error": yaml otherwise prints its own warnings through
-    // process.emitWarning, naming no file - `date: {{ date }}` printed
-    // "Keys with collection values will be stringified". A value vowel
-    // reads is checked by coerce(), which reports it with the path.
-    const parsed = yaml.parse(node.value, { logLevel: "error" })
-    if (parsed === null || parsed === undefined) return {}
-    if (!isPlainObject(parsed)) {
-      report(`${filePath}: frontmatter is ${Array.isArray(parsed) ? "a list" : "a single value"}, not a mapping; rendering it as content`)
-      return asContent(tree, node)
-    }
-    return parsed
-  } catch (error) {
-    report(`${filePath}: frontmatter could not be parsed (${String(error.message).split("\n")[0]}); rendering it as content`)
+  // logLevel "error": yaml otherwise prints its own warnings through
+  // process.emitWarning, naming no file - `date: {{ date }}` printed
+  // "Keys with collection values will be stringified". A value vowel
+  // reads is checked by coerce(), which reports it with the path.
+  const lines = new LineCounter()
+  const document = yaml.parseDocument(node.value, { lineCounter: lines, logLevel: "error" })
+  const [error] = document.errors
+  if (error) {
+    // Its own "at line 1, column 17" counts from the block, not the file.
+    const detail = String(error.message).split("\n")[0].replace(/ at line \d+, column \d+:?$/, "")
+    report(`${sourceLocation(filePath, filePoint(node, error.linePos?.[0]))}: frontmatter could not be parsed (${detail}); rendering it as content`)
+    return asContent(tree, node)
+  }
+  const parsed = document.toJS()
+  if (parsed === null || parsed === undefined) return { values: {}, points: {} }
+  if (!isPlainObject(parsed)) {
+    report(`${sourceLocation(filePath, node.position?.start)}: frontmatter is ${Array.isArray(parsed) ? "a list" : "a single value"}, not a mapping; rendering it as content`)
     return asContent(tree, node)
   }
+  return { values: parsed, points: keyPoints(node, document, lines) }
 }
 
 /**
@@ -276,4 +328,4 @@ function asContent(tree, node) {
   return undefined
 }
 
-export { EXPECTED, STATUSES, coerce, parseFrontmatter, resolvePath, toISODate }
+export { EXPECTED, STATUSES, coerce, parseFrontmatter, frontmatterPoints, resolvePath, toISODate }

package/plugins/markdown/index.js

@@ -13,7 +13,8 @@ import { gfmTable } from 'micromark-extension-gfm-table'
 import { gfmTableFromMarkdown } from 'mdast-util-gfm-table'
 import { normalizeHeadingLevels } from './metadata.js'
 import { readFileSync } from "fs"
-import { createHashtagPage, labelFromName, showPages } from "./../../utils.js"
+import { createHashtagPage, labelFromName, showPages, sourceLocation } from "./../../utils.js"
+import { frontmatterPoints } from "./frontmatter.js"
 import { toHast, defaultHandlers } from 'mdast-util-to-hast'
 import { toString as hastToString } from 'hast-util-to-string'
 import getMetadata, { imageFromPage, reservedProperties } from "./metadata.js"
@@ -21,6 +22,7 @@ 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"
 
@@ -148,14 +150,20 @@ function readFile(source, { api, config }) {
     // highlight contains anything else: `**March 4, 2026**` threw
     // "Cannot compile unknown node `strong`", and a link, emphasis or
     // inline code in the same position threw on their own types.
+    // Each element keeps its node's position, as the built-in handlers'
+    // do, so a warning at write names the line (an unresolved wikilink).
     unknownHandler: (state, node) => {
-      if (node.type === "highlight") return h("mark", state.all(node))
-      if (node.type === "time") return h("time", { datetime: node.datetime }, state.all(node))
+      const positioned = (element) => {
+        state.patch(node, element)
+        return element
+      }
+      if (node.type === "highlight") return positioned(h("mark", state.all(node)))
+      if (node.type === "time") return positioned(h("time", { datetime: node.datetime }, state.all(node)))
       // Parsed at read, resolved at write (writeRules.js): the element
       // carries what the write needs, and what the editor needs to put
       // the directive back.
-      if (node.type === "wikilink") return h("a.wikilink", { "data-note": node.name, "data-section": node.section }, state.all(node))
-      if (node.type === "icon") return h("img.icon", { "data-icon": node.name, alt: node.name.split("/").at(-1) })
+      if (node.type === "wikilink") return positioned(h("a.wikilink", { "data-note": node.name, "data-section": node.section }, state.all(node)))
+      if (node.type === "icon") return positioned(h("img.icon", { "data-icon": node.name, alt: node.name.split("/").at(-1) }))
     }
   })
 
@@ -189,7 +197,7 @@ function readFile(source, { api, config }) {
     data: string,
     write: metadata.html_file ?? true,
     metadata: withDeclaredTypes({ ...targetMetadata, hastAbstract: hast }),
-    settings: pathInfo.base === "settings.md" ? settingsContribution(metadata, filePath, config?.log) : undefined
+    settings: pathInfo.base === "settings.md" ? settingsContribution(metadata, filePath, config?.log, mdast.children.find(child => child.type === "yaml")) : undefined
   }
 }
 
@@ -225,13 +233,22 @@ function withDeclaredTypes(metadata) {
  * @param {Record<string, any>} metadata
  * @param {string} filePath
  * @param {(level: string, message: string) => void} [log]
+ * @param {object} [yamlNode] - its frontmatter, for the warnings' lines
  */
-function settingsContribution(metadata, filePath, log) {
+function settingsContribution(metadata, filePath, log, yamlNode) {
+  // Each warning names the key's line. Found only when there is one to
+  // give, since it parses the block again.
+  const at = (key) => sourceLocation(filePath, yamlNode ? frontmatterPoints(yamlNode)[key] : undefined)
   if (metadata.fm_title !== undefined && metadata.fm_name === undefined) {
-    log?.("warn", `${filePath}: \`title:\` in a settings file does nothing - the site's name is \`name:\``)
+    log?.("warn", `${at("title")}: \`title:\` in a settings file does nothing - the site's name is \`name:\``)
   }
   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`)
+    log?.("warn", `${at("slogan")}: \`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", `${at("markdown_mirror")}: \`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))
@@ -242,19 +259,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"
-  }
-}
 
 
 
@@ -491,8 +495,7 @@ const readMarkdown = {
   router,
   createStubs,
   expandStubs,
-  readFile,
-  writeFile: writeMarkdown
+  readFile
 }
 
 
@@ -500,7 +503,7 @@ const readMarkdown = {
 /** @type {Votive.VotivePlugin} */
 const vowelMarkdownPlugin = {
   name: "vowel",
-  processors: [readMarkdown]
+  processors: [readMarkdown, mirrorStubs, mirrorWriter]
 }
 
 export default vowelMarkdownPlugin

package/plugins/markdown/metadata.js

@@ -79,6 +79,7 @@ export const reservedProperties = [
   "rss_item",
   "sitemap_item",
   "html_file",
+  "markdown_mirror",
   "global_nav_item",
   "local_nav_item",
   "theme",
@@ -238,10 +239,11 @@ function markAsNatural(block, kind) {
  * @param {(message: string) => void} report
  */
 function readFrontmatter(tree, node, metadata, filePath, folder, report) {
-  const parsed = parseFrontmatter(tree, node, filePath, report)
-  if (!parsed) return
+  const read = parseFrontmatter(tree, node, filePath, report)
+  if (!read) return
 
-  const frontmatter = coerce(parsed, filePath, folder, report)
+  const parsed = read.values
+  const frontmatter = coerce(parsed, filePath, folder, report, read.points)
 
   for (const key in frontmatter) {
     const name = reservedProperties.includes(key) ? key : "fm_" + key

package/plugins/markdown/mirror.js

@@ -0,0 +1,121 @@
+import path from "node:path"
+import { contentSection } from "../xml/entryContent.js"
+import { markdownBody } from "../atproto/body.js"
+import { isMirrored } from "../../utils.js"
+
+/** @import * as Votive from "votive" */
+
+/**
+ * A page's markdown mirror: `/blog/post.md` beside `/blog/post`, the post
+ * as the reader sees it, in portable markdown. Off by default. The root
+ * settings.md's `markdown_mirror: true` mirrors every page, and a page's
+ * own `markdown_mirror` overrides it; a page with `html_file: false`
+ * is mirrored only when it asks itself, which makes a page whose only
+ * file is its markdown.
+ *
+ * A mirror is a stub of its own source type, `.markdownmirror`, so the
+ * markdown processor never reads it as a page. Its stub path is the
+ * page's *target* path, which routing has already lowercased and
+ * hashed, so a secret page's mirror sits beside its hashed url. A page
+ * that stops being mirrored is no longer declared, and votive removes
+ * its mirror and the file.
+ *
+ * The enumerator sees only the root's settings, so a subfolder's
+ * settings.md cannot switch mirrors (the markdown read warns).
+ * @type {Votive.ProcessorStubs}
+ */
+function createStubs({ api, settings }) {
+  const siteMirrors = settings.lastNonNull("markdown_mirror") === true
+
+  // Off by default, and then only a page that asks for its own mirror
+  // can have one: one filtered query rather than every page on every pass.
+  const candidates = siteMirrors
+    ? api.targets({ folder: "", recursive: true })
+    : api.targets({ folder: "", recursive: true, query: { markdown_mirror: true } })
+
+  const pages = candidates.filter(page => isMirrored(page, siteMirrors))
+  return pages.map(page => ({
+    path: page.path.replace(/\.html$/, ".markdownmirror"),
+    params: { page: page.path }
+  }))
+}
+
+/** @type {Votive.ProcessorExpand} */
+function expandStubs({ params }) {
+  return { text: params.page }
+}
+
+/**
+ * A long date in English, as the page shows it, read in UTC: a date is
+ * stored as UTC midnight, and local time west of UTC is the day before.
+ * @param {string} iso
+ */
+function longDate(iso) {
+  const date = new Date(iso)
+  if (isNaN(Number(date))) return undefined
+  return date.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" })
+}
+
+/**
+ * The mirror is made from the page's rendered `section#content`, not
+ * from the author's source, whose wikilinks, listing directives and
+ * `:icons:` mean nothing outside vowel. The page is a tracked read, so
+ * re-rendering it rewrites its mirror.
+ *
+ * On a pass that writes the mirror before its page, the page's `data` is
+ * still its markdown and has no `section#content`. Then nothing is
+ * written: the page's write stores its HTML, which restales the mirror,
+ * and the same pass writes it again.
+ * @type {Votive.ProcessorWrite}
+ */
+function writeMirror(target, { api, settings }) {
+  const page = api.target(target.metadata.markdown_mirror_of)
+  if (!page) return
+
+  const section = contentSection(page.data)
+  if (!section) return
+
+  // A page without a file has no url of its own, so its mirror names
+  // itself.
+  const ownURL = "/" + String(target.path).split(path.sep).join("/")
+  const pagePath = page.write === false ? ownURL : page.metadata.prettyURL
+  const domain = settings.lastNonNull("fm_domain")
+  const origin = domain ? (String(domain).startsWith("http") ? String(domain) : "https://" + domain) : undefined
+  const url = origin ? new URL(pagePath, origin).href : pagePath
+
+  const title = page.metadata.title
+  const date = page.metadata.date ? longDate(page.metadata.date) : undefined
+  const byline = [date, url].filter(part => part).join(" · ")
+  const body = markdownBody(section, url)
+
+  const parts = [title ? `# ${title}` : undefined, byline, body].filter(part => part)
+  return { data: parts.join("\n\n") + "\n" }
+}
+
+/**
+ * The stub's processor. Its router puts `blog/post.markdownmirror` at
+ * `blog/post.md`.
+ * @type {Votive.VotiveProcessor}
+ */
+const mirrorStubs = {
+  extensions: [".markdownmirror"],
+  format: "text",
+  router: ({ dir, name }) => ({ dir, name, ext: ".md" }),
+  createStubs,
+  expandStubs,
+  readFile: (source) => ({ data: "", metadata: { markdown_mirror_of: source.text } })
+}
+
+/**
+ * The only processor that writes `.md` targets. It reads nothing, so it
+ * needs no format: every `.md` source is the markdown processor's. A
+ * write is matched on the target's extension, so a second `writeFile`
+ * for `.md` would run on every mirror too.
+ * @type {Votive.VotiveProcessor}
+ */
+const mirrorWriter = {
+  extensions: [".md"],
+  writeFile: writeMirror
+}
+
+export { mirrorStubs, mirrorWriter }

package/plugins/markdown/visitor.js

@@ -33,6 +33,43 @@
 
 const SKIP = Symbol("skip")
 
+/**
+ * The point `index` characters into a text node, from the node's own
+ * start: what an inline rule's node is given as its position, so a
+ * warning about it (an unresolved wikilink) can name its line. Exact
+ * for the line; the column can be off where the text's value differs
+ * from the source - an escape earlier on the line, or a `> ` the
+ * value doesn't hold.
+ * @param {{ line: number, column: number, offset?: number }} start
+ * @param {string} value
+ * @param {number} index
+ */
+function pointAt(start, value, index) {
+  const before = value.slice(0, index)
+  const lines = before.split("\n")
+  const offset = start.offset === undefined ? undefined : start.offset + index
+  if (lines.length === 1) return { line: start.line, column: start.column + index, offset }
+  return { line: start.line + lines.length - 1, column: lines.at(-1).length + 1, offset }
+}
+
+/**
+ * Gives a rule's nodes the span of their match, unless the rule set
+ * one. Nothing when the text node had no position (a node the build
+ * made).
+ * @param {Node[]} nodes
+ * @param {Node} text - the text node the match is in
+ * @param {RegExpExecArray} match
+ */
+function withPosition(nodes, text, match) {
+  const start = text.position?.start
+  if (!start) return nodes
+  const span = {
+    start: pointAt(start, text.value, match.index),
+    end: pointAt(start, text.value, match.index + match[0].length)
+  }
+  return nodes.map(node => node.position || node.type === "text" ? node : { ...node, position: span })
+}
+
 /**
  * @param {object} rules
  * @param {InlineRule[]} [rules.inline]
@@ -46,11 +83,12 @@ function createVisitor({ inline = [], block = [], skip = () => false } = {}) {
   /**
    * Text into the pieces the inline rules make of it. Returns null when
    * no rule matched, so an untouched node is left in place unchanged.
-   * @param {string} value
+   * @param {Node} text - a text node
    * @param {any} context
    * @returns {Node[] | null}
    */
-  function applyInline(value, context) {
+  function applyInline(text, context) {
+    const value = text.value
     const pieces = []
     let cursor = 0
     let touched = false
@@ -79,7 +117,7 @@ function createVisitor({ inline = [], block = [], skip = () => false } = {}) {
       touched = true
       const before = value.slice(pieces.length ? pieces.at(-1).end : 0, match.index)
       if (before) pieces.push({ end: match.index, nodes: [{ type: "text", value: before }] })
-      pieces.push({ end, nodes: Array.isArray(resolved) ? resolved : [resolved] })
+      pieces.push({ end, nodes: withPosition(Array.isArray(resolved) ? resolved : [resolved], text, match) })
       cursor = end
     }
 
@@ -113,7 +151,7 @@ function createVisitor({ inline = [], block = [], skip = () => false } = {}) {
     if (skip(node)) return 1
 
     if (node.type === "text" && typeof node.value === "string") {
-      const pieces = applyInline(node.value, context)
+      const pieces = applyInline(node, context)
       if (!pieces) return 1
       parent.children.splice(index, 1, ...pieces)
       return pieces.length

package/plugins/secret-pages/index.js

@@ -6,14 +6,16 @@ import { isSecretPath } from "../../secretPaths.js"
 /**
  * Where your secret pages are. A page under a `##` segment is published
  * at a hashed url that nothing on the site links to, so the author needs
- * another way to find it: the dev server prints each one, file and url,
- * when it first sees it - every one at startup, then each new one (or a
- * renamed one, whose url changed) as it appears.
+ * another way to find it: every build prints each one, file and url,
+ * when it first sees it - every one at the first pass, then each new one
+ * (or a renamed one, whose url changed) as it appears.
  *
- * **Only the dev server.** `init()` turns this on with
- * `config.announceSecretPages`; `deploy`, `publish` and a plain build
- * never do. Those run in CI too, where logs are kept and can be public,
- * and a logged url is exactly what the hash exists to keep private.
+ * **Every build, CI included** (per Sam, Nov 5 2026). It used to be the
+ * dev server's alone, to keep the urls out of logs that might be public.
+ * That was theatre: a secret page's url is an unkeyed hash of its source
+ * path, so whoever has the source has the url, and hiding it from a log
+ * suggested a protection that isn't there. Only `logging: "silent"`
+ * turns it off.
  *
  * It is a stub enumerator that declares no stubs: the one hook that runs
  * on every pass and can list pages. It lists only the hidden ones - a
@@ -41,7 +43,7 @@ function pageURL(domain, prettyURL) {
 
 /** @type {Votive.ProcessorStubs} */
 function createStubs({ api, settings, config }) {
-  if (!config.announceSecretPages || config.logging === "silent") return []
+  if (config.logging === "silent") return []
 
   const seen = announced.get(config) ?? new Set()
   announced.set(config, seen)

package/stylesheets/DefaultStyles.css

@@ -614,78 +614,78 @@
 			display: none;
 		}
 	}
-}
-
-/* footer */
 
-footer {
+	/* footer */
 
-	text-align: center;
-	display: flex;
-	flex-direction: column;
-	align-items: center;
-	gap: 2lh;
+	footer {
 
-	nav ul {
-		list-style: none;
-		padding: 0;
+		text-align: center;
 		display: flex;
-		gap: 1ch;
+		flex-direction: column;
+		align-items: center;
+		gap: 2lh;
 
-		img {
-			height: 1em;
-			width: auto;
+		nav ul {
+			list-style: none;
+			padding: 0;
+			display: flex;
+			gap: 1ch;
+
+			img {
+				height: 1em;
+				width: auto;
+			}
 		}
-	}
 
-	section {
-		display: block;
-	}
+		section {
+			display: block;
+		}
 
-	a {
+		a {
 
-		&,
-		&:visited {
+			&,
+			&:visited {
 
-			color: var(--color-link-body);
-		}
+				color: var(--color-link-body);
+			}
 
-		&:hover {
-			color: var(--color-link-hover-menu);
+			&:hover {
+				color: var(--color-link-hover-menu);
+			}
 		}
+
 	}
 
-}
+	/* homepage */
+	@media (min-width: 140rch) {
+		body.page_home {
+			grid-template-columns: 1fr 15rch 70rch 15rch 1fr;
+		}
+	}
 
-/* homepage */
-@media (min-width: 140rch) {
 	body.page_home {
-		grid-template-columns: 1fr 15rch 70rch 15rch 1fr;
-	}
-}
 
-body.page_home {
 
+		/*
+			The homepage's slogan is the hero
+		*/
+		main>[itemprop="slogan"] {
+			font-size: 4em;
+			font-weight: bold;
+			padding-block: 0.5lh;
 
-	/*
-		The homepage's slogan is the hero
-	*/
-	main>[itemprop="slogan"] {
-		font-size: 4em;
-		font-weight: bold;
-		padding-block: 0.5lh;
 
+		}
 
-	}
+		/*
+			Hide breadcrumbs
+		*/
+		[aria-label=Breadcrumbs],
+		[aria-label=Contents],
+		&>aside>nav,
+		&>main>h1 {
+			display: none;
+		}
 
-	/*
-		Hide breadcrumbs
-	*/
-	[aria-label=Breadcrumbs],
-	[aria-label=Contents],
-	&>aside>nav,
-	&>main>h1 {
-		display: none;
 	}
-
-}
+}

package/utils.js

@@ -99,6 +99,23 @@ export function toTitleCase(string) {
   }).join(" ")
 }
 
+/**
+ * Where a problem is, the way editors and terminals read it:
+ * `blog/post.md:6:15`, which VS Code's terminal opens at that line and
+ * column. The file alone when there is no position: a problem with the
+ * whole file, or a node the build made rather than read. The path is
+ * the source's as written, salt and all: a secret page is not secret
+ * from whoever can read the project, so hiding it here would only
+ * pretend otherwise (per Sam).
+ * @param {string} file - a source path
+ * @param {{ line?: number, column?: number }} [point] - a node's `position.start`
+ */
+export function sourceLocation(file, point) {
+  if (!point?.line) return file
+  if (!point.column) return `${file}:${point.line}`
+  return `${file}:${point.line}:${point.column}`
+}
+
 /**
  * A tag page's markdown: a title and the glob directive that lists every
  * page carrying the tag.
@@ -171,6 +188,32 @@ export function isPageWithoutFile(target) {
   return target.write === false && target.metadata?.html_file === false
 }
 
+/**
+ * Whether a page has a markdown mirror (plugins/markdown/mirror.js).
+ * The root settings.md's `markdown_mirror` switches every page, and the
+ * page's own key overrides it. A page without a file is mirrored only
+ * when it asks itself: `html_file: false` used to mean "published
+ * nowhere", and switching mirrors on for a site must not publish it.
+ * Another virtual page (`status: deleted`) is never mirrored.
+ * @param {any} page
+ * @param {boolean} siteMirrors - the root settings.md's `markdown_mirror`
+ */
+export function isMirrored(page, siteMirrors) {
+  if (page.extension !== ".html") return false
+  const own = page.metadata?.markdown_mirror
+  if (isPageWithoutFile(page)) return own === true
+  if (page.write === false) return false
+  return typeof own === "boolean" ? own : siteMirrors
+}
+
+/**
+ * Where a page's mirror is: `blog/post.html` → `blog/post.md`.
+ * @param {string} pagePath - a stored target path
+ */
+export function mirrorPath(pagePath) {
+  return pagePath.replace(/\.html$/, ".md")
+}
+
 /**
  * listPages, plus pages without a file: for listings, cards and the
  * feed, which can show a page without linking to it.