vowel 0.7.4 → 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.4",
+  "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/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

@@ -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
@@ -788,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)
@@ -798,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
@@ -220,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]
@@ -230,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) }
 }
 
 /**
@@ -277,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"
@@ -149,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) }))
     }
   })
 
@@ -190,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
   }
 }
 
@@ -226,18 +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", `${filePath}: \`markdown_mirror:\` works only in the root settings.md or in a page's frontmatter`)
+    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))

package/plugins/markdown/metadata.js

@@ -239,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/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/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.