livemark 0.28.2 → 0.28.4

package/source/commands/start.ts

@@ -1,8 +1,10 @@
+import { watch } from "node:fs"
 import { join } from "node:path"
 import { Command } from "commander"
 import { createServer } from "vite"
 
 const configFile = join(import.meta.dirname, "..", "..", "source", "vite.config.ts")
+const IGNORED_DIRS = /(^|[/\\])(node_modules|\.git|\.livemark)([/\\]|$)/
 
 /**
  * Start a development server.
@@ -10,6 +12,13 @@ const configFile = join(import.meta.dirname, "..", "..", "source", "vite.config.
 export const start = new Command("start")
   .description("Start a live server")
   .action(async () => {
+    await startServer()
+  })
+
+// A broken config fails `createServer` before Vite's watcher exists, so without this
+// the process exits and the fix has nobody to pick it up.
+async function startServer() {
+  try {
     const server = await createServer({
       configFile,
       server: { port: 8000, host: true },
@@ -17,4 +26,19 @@ export const start = new Command("start")
     await server.listen()
     server.printUrls()
     server.bindCLIShortcuts({ print: true })
+  } catch (error) {
+    console.error(error)
+    console.error("\nWaiting for a file change to retry…")
+    await waitForChange(process.cwd())
+    await startServer()
+  }
+}
+
+function waitForChange(dir: string) {
+  return new Promise<void>(resolve => {
+    const watcher = watch(dir, { recursive: true, ignore: IGNORED_DIRS }, () => {
+      watcher.close()
+      resolve()
+    })
   })
+}

package/source/content-collections.ts

@@ -236,7 +236,7 @@ const articles = defineCollection({
         ],
       },
     )
-    const tocItems = extractToc(content)
+    const tocItems = extractToc(bodyContent)
     const searchText = extractSearchText(content)
     const lastUpdated = lastUpdatedByFile.get(doc._meta.filePath)
     const image = doc.image

package/source/helpers/local-imports.ts

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+
+// Enough for this repo's own source, which always imports by full relative path.
+const RELATIVE_IMPORT = /(?:from|import)\s*["'](\.{1,2}\/[^"']+)["']/g
+
+/** The module and every file it reaches through relative imports, as absolute paths. */
+export function collectLocalImports(entry: string) {
+  const seen = new Set<string>()
+  const queue = [resolve(entry)]
+  for (const file of queue) {
+    if (seen.has(file) || !existsSync(file)) continue
+    seen.add(file)
+    for (const [, specifier] of readFileSync(file, "utf8").matchAll(RELATIVE_IMPORT)) {
+      if (specifier) queue.push(resolve(dirname(file), specifier))
+    }
+  }
+  return [...seen]
+}

package/source/helpers/local-imports.unit.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { collectLocalImports } from "./local-imports.ts"
+
+describe("collectLocalImports", () => {
+  it("should follow relative imports transitively and skip packages", () =>
+    temporaryDirectoryTask(tmpDir => {
+      fs.mkdirSync(join(tmpDir, "lib"))
+      fs.writeFileSync(
+        join(tmpDir, "entry.ts"),
+        'import { a } from "./lib/a.ts"\nimport { z } from "zod"\n',
+      )
+      fs.writeFileSync(
+        join(tmpDir, "lib", "a.ts"),
+        'import "../b.ts"\nexport const a = 1\n',
+      )
+      fs.writeFileSync(join(tmpDir, "b.ts"), 'export * from "./entry.ts"\n')
+      expect(collectLocalImports(join(tmpDir, "entry.ts")).sort()).toEqual(
+        [
+          join(tmpDir, "b.ts"),
+          join(tmpDir, "entry.ts"),
+          join(tmpDir, "lib", "a.ts"),
+        ].sort(),
+      )
+    }))
+
+  it("should skip imports that do not resolve to a file", () =>
+    temporaryDirectoryTask(tmpDir => {
+      fs.writeFileSync(join(tmpDir, "entry.ts"), 'import "./missing.ts"\n')
+      expect(collectLocalImports(join(tmpDir, "entry.ts"))).toEqual([
+        join(tmpDir, "entry.ts"),
+      ])
+    }))
+})

package/source/helpers/task-queue.ts

@@ -0,0 +1,28 @@
+/** Run keyed async tasks one at a time; a key enqueued again before its task
+ *  starts replaces it, so a burst of events for one file costs one run. */
+export function createTaskQueue(props: { onError: (error: unknown) => void }) {
+  const pending = new Map<string, () => Promise<unknown>>()
+  let draining: Promise<void> | undefined
+
+  return {
+    enqueue(key: string, task: () => Promise<unknown>) {
+      pending.set(key, task)
+      draining ??= drain()
+      return draining
+    },
+  }
+
+  async function drain() {
+    // A Map iterator also visits entries set during iteration, which is what
+    // picks up keys enqueued while a task runs.
+    for (const [key, task] of pending) {
+      pending.delete(key)
+      try {
+        await task()
+      } catch (error) {
+        props.onError(error)
+      }
+    }
+    draining = undefined
+  }
+}

package/source/helpers/task-queue.unit.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vite-plus/test"
+import { createTaskQueue } from "./task-queue.ts"
+
+describe("createTaskQueue", () => {
+  it("runs one task at a time", async () => {
+    const queue = createTaskQueue({ onError: () => {} })
+    const log: string[] = []
+    const task = (name: string, ms: number) => async () => {
+      log.push(`start ${name}`)
+      await new Promise(resolve => setTimeout(resolve, ms))
+      log.push(`end ${name}`)
+    }
+    queue.enqueue("a", task("a", 30))
+    await queue.enqueue("b", task("b", 1))
+    expect(log).toEqual(["start a", "end a", "start b", "end b"])
+  })
+
+  it("collapses a key enqueued again before it starts", async () => {
+    const queue = createTaskQueue({ onError: () => {} })
+    const runs: string[] = []
+    queue.enqueue("first", async () => runs.push("first"))
+    queue.enqueue("file", async () => runs.push("stale"))
+    await queue.enqueue("file", async () => runs.push("latest"))
+    expect(runs).toEqual(["first", "latest"])
+  })
+
+  it("reruns a key enqueued while it is running", async () => {
+    const queue = createTaskQueue({ onError: () => {} })
+    const runs: number[] = []
+    let release = () => {}
+    queue.enqueue("file", async () => {
+      runs.push(1)
+      await new Promise<void>(resolve => (release = resolve))
+    })
+    const done = queue.enqueue("file", async () => runs.push(2))
+    release()
+    await done
+    expect(runs).toEqual([1, 2])
+  })
+
+  it("reports a failed task and keeps draining", async () => {
+    const errors: unknown[] = []
+    const queue = createTaskQueue({ onError: error => errors.push(error) })
+    const runs: string[] = []
+    queue.enqueue("a", async () => {
+      throw new Error("boom")
+    })
+    await queue.enqueue("b", async () => runs.push("b"))
+    expect(errors).toHaveLength(1)
+    expect(runs).toEqual(["b"])
+  })
+
+  it("starts a fresh drain after the previous one finished", async () => {
+    const queue = createTaskQueue({ onError: () => {} })
+    const runs: string[] = []
+    await queue.enqueue("a", async () => runs.push("a"))
+    await queue.enqueue("a", async () => runs.push("again"))
+    expect(runs).toEqual(["a", "again"])
+  })
+})

package/source/helpers/toc.ts

@@ -1,4 +1,10 @@
-import GithubSlugger from "github-slugger"
+import GithubSlugger, { slug as slugOnce } from "github-slugger"
+import type { Root } from "mdast"
+import { toString } from "mdast-util-to-string"
+import remarkGfm from "remark-gfm"
+import remarkParse from "remark-parse"
+import { unified } from "unified"
+import { visit } from "unist-util-visit"
 import type { TocItem } from "../models/toc.ts"
 
 const CUSTOM_ID_PATTERN = /\s*\[#([^\]]+)\]\s*$/
@@ -6,41 +12,35 @@ const TOC_HIDDEN_PATTERN = /\s*\[!toc\]\s*$/
 const TOC_ONLY_PATTERN = /\s*\[toc\]\s*$/
 const STEP_PATTERN = /\s*\[step\]\s*$/
 
-/** Extract TOC headings from raw markdown content */
+/** Extract TOC headings from markdown content, with ids matching the rendered headings */
 export function extractToc(content: string): TocItem[] {
+  const tree: Root = unified().use(remarkParse).use(remarkGfm).parse(content)
   const slugger = new GithubSlugger()
   const items: TocItem[] = []
-  const headingRegex = /^(#{2,4})\s+(.+)$/
-  const lines = content.split("\n")
-  let inCodeBlock = false
 
-  for (const line of lines) {
-    if (line.startsWith("```") || line.startsWith("````")) {
-      inCodeBlock = !inCodeBlock
-      continue
+  // rehype-slug numbers duplicates across every rendered heading, so hidden, step and
+  // out-of-range headings advance the slugger; `[toc]` ones are never rendered, so do not
+  visit(tree, "heading", node => {
+    const lastChild = node.children.at(-1)
+    const marker = lastChild?.type === "text" ? lastChild.value : ""
+    const isTocOnly = TOC_ONLY_PATTERN.test(marker)
+    const isHidden = TOC_HIDDEN_PATTERN.test(marker) || STEP_PATTERN.test(marker)
+    const customId = CUSTOM_ID_PATTERN.exec(marker)?.[1]
+
+    if (lastChild?.type === "text") {
+      lastChild.value = marker
+        .replace(CUSTOM_ID_PATTERN, "")
+        .replace(TOC_ONLY_PATTERN, "")
+        .replace(TOC_HIDDEN_PATTERN, "")
+        .replace(STEP_PATTERN, "")
     }
-    if (inCodeBlock) continue
 
-    const match = headingRegex.exec(line)
-    if (!match) continue
+    const title = toString(node).trim()
+    const slug = customId ?? (isTocOnly ? slugOnce(title) : slugger.slug(title))
 
-    const depth = match[1]!.length
-    const rawTitle = match[2]!
-
-    if (TOC_HIDDEN_PATTERN.test(rawTitle)) continue
-    if (STEP_PATTERN.test(rawTitle)) continue
-
-    const idMatch = CUSTOM_ID_PATTERN.exec(rawTitle)
-    const title = rawTitle
-      .replace(CUSTOM_ID_PATTERN, "")
-      .replace(TOC_ONLY_PATTERN, "")
-      .replace(STEP_PATTERN, "")
-      .replace(/\*\*(.+?)\*\*/g, "$1")
-      .replace(/`(.+?)`/g, "$1")
-    const slug = idMatch?.[1] ?? slugger.slug(title)
-
-    items.push({ url: `#${slug}`, title, depth })
-  }
+    if (isHidden || node.depth < 2 || node.depth > 4) return
+    items.push({ url: `#${slug}`, title, depth: node.depth })
+  })
 
   return items
 }

package/source/helpers/toc.unit.ts

@@ -60,6 +60,33 @@ describe("extractToc", () => {
     ])
   })
 
+  it("should render link and emphasis headings as plain text", () => {
+    const content =
+      "## [0.6.0](https://github.com/o/r/compare/v0.5.0...v0.6.0) (2026-10-20)\n\n" +
+      "### *Bug* ~~Fixes~~"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#060-2026-10-20", title: "0.6.0 (2026-10-20)", depth: 2 },
+      { url: "#bug-fixes", title: "Bug Fixes", depth: 3 },
+    ])
+  })
+
+  it("should number duplicate slugs counting hidden and h1 headings", () => {
+    const content =
+      "# Features\n\n## Features [!toc]\n\n## Features\n\n### Features [step]\n\n## Features"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#features-2", title: "Features", depth: 2 },
+      { url: "#features-4", title: "Features", depth: 2 },
+    ])
+  })
+
+  it("should ignore headings inside code fences", () => {
+    const content = "## Real\n\n```md\n## Fake\n```"
+    const toc = extractToc(content)
+    expect(toc).toEqual([{ url: "#real", title: "Real", depth: 2 }])
+  })
+
   it("should include [toc] headings with annotation stripped from title", () => {
     const content = "## Regular\n\n## TOC Only [toc]\n\n## Another"
     const toc = extractToc(content)

package/source/models/config.ts

@@ -106,6 +106,7 @@ export type SystemConfig = z.infer<typeof SystemConfig>
 export const SystemConfig = z.object({
   root: z.string(),
   configPath: z.string(),
+  configDependencies: z.array(z.string()).default([]),
 })
 
 /**

package/source/plugins/vite-content.ts

@@ -0,0 +1,72 @@
+import { existsSync, watch, type FSWatcher } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { createBuilder } from "@content-collections/core"
+import { configureLogging } from "@content-collections/integrations"
+import type { Plugin } from "vite"
+import { createTaskQueue } from "../helpers/task-queue.ts"
+
+export interface ContentOptions {
+  configPath: string
+  contentDir: string
+}
+
+type Builder = Awaited<ReturnType<typeof createBuilder>>
+
+const IGNORED_PATHS = /(^|[/\\])(node_modules|\.[^/\\]+)([/\\]|$)/
+
+/** Build the content collections and rebuild them on edits, one build at a time:
+ *  `@content-collections/vite` builds per file event, a save fires two, and their
+ *  overlapping writes tore `allArticles.js` so every request failed. */
+export function content(opts: ContentOptions): Plugin {
+  const queue = createTaskQueue({ onError: error => console.error(error) })
+  let builder: Builder | undefined
+  let initialBuild: Promise<void> | undefined
+  let watcher: FSWatcher | undefined
+  return {
+    name: "livemark:content",
+    config(config) {
+      const configPath = resolve(config.root ?? process.cwd(), opts.configPath)
+      const generated = join(dirname(configPath), ".content-collections", "generated")
+      return {
+        optimizeDeps: { exclude: ["content-collections"] },
+        resolve: { alias: { "content-collections": generated } },
+        ...((config.server?.fs?.allow?.length ?? 0) > 0 && {
+          server: { fs: { allow: [generated] } },
+        }),
+      }
+    },
+    async configResolved(config) {
+      builder = await createBuilder(resolve(config.root, opts.configPath))
+      configureLogging(builder)
+    },
+    buildStart() {
+      const current = builder
+      if (!current) return
+      // Once, not per environment, and through the queue so an edit landing
+      // before it cannot overlap it.
+      initialBuild ??= new Promise((resolve, reject) => {
+        queue.enqueue("build", () => current.build().then(resolve, reject))
+      })
+      return initialBuild
+    },
+    configureServer() {
+      const current = builder
+      if (!current) return
+      watcher = watch(
+        opts.contentDir,
+        { recursive: true, ignore: IGNORED_PATHS },
+        (_, filename) => {
+          if (!filename) return
+          const file = join(opts.contentDir, filename)
+          queue.enqueue(file, () =>
+            current.sync(existsSync(file) ? "update" : "delete", file),
+          )
+        },
+      )
+    },
+    closeBundle() {
+      watcher?.close()
+      watcher = undefined
+    },
+  }
+}

package/source/plugins/vite-livemark.ts

@@ -1,9 +1,10 @@
-import { cpSync, existsSync, rmSync, statSync } from "node:fs"
-import { join, sep } from "node:path"
-import type { ConfigEnv, Plugin, UserConfig as ViteUserConfig } from "vite"
+import { cpSync, existsSync, readFileSync, rmSync, statSync } from "node:fs"
+import { dirname, join, sep } from "node:path"
+import type { ConfigEnv, Plugin, UserConfig as ViteUserConfig, ViteDevServer } from "vite"
 import { mergeConfig } from "vite"
 import packageJson from "../../package.json" with { type: "json" }
 import { buildTarget } from "../actions/target/build.ts"
+import { collectLocalImports } from "../helpers/local-imports.ts"
 import { renderInlineMarkdown } from "../helpers/render-inline-markdown.ts"
 import { excludeTailwindSources } from "../helpers/tailwind-sources.ts"
 import { resolveTargetExport } from "../helpers/target-export.ts"
@@ -17,6 +18,13 @@ export interface LivemarkOptions {
 
 const SOURCE_DIR = join(import.meta.dirname, "..")
 const IS_INSTALLED = SOURCE_DIR.includes(`${sep}node_modules${sep}`)
+const LOCKFILES = [
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+]
 
 /** Single virtual module exposing livemark's runtime values to consumer
  *  override files via named exports:
@@ -102,18 +110,29 @@ export function livemark(opts: LivemarkOptions): Plugin {
       ].join("\n")
     },
     configureServer(server) {
+      // Vite restarts only for its own config's imports; the project config's
+      // imports and, in livemark's own dev, the content-collections config's
+      // imports need it too. A restart rebuilds the target, so no sync is lost.
+      const restartFiles = new Set([
+        opts.config.configPath,
+        ...opts.config.configDependencies,
+        ...(IS_INSTALLED
+          ? []
+          : collectLocalImports(join(SOURCE_DIR, "content-collections.ts"))),
+      ])
       // Vite watches only its root (the target); the files the target is
       // copied from join its watcher here. `.livemark/` always exists
       // because the target lives inside it.
-      server.watcher.add([opts.config.configPath, overridesRoot])
-      if (!IS_INSTALLED) server.watcher.add(SOURCE_DIR)
+      server.watcher.add([...restartFiles, overridesRoot])
+      if (IS_INSTALLED) watchInstalledVersion(server, opts.config.root)
+      else server.watcher.add(SOURCE_DIR)
       server.watcher.on("change", file => onChange(file, "change"))
       server.watcher.on("add", file => onChange(file, "add"))
       server.watcher.on("unlink", file => onChange(file, "unlink"))
       server.watcher.on("unlinkDir", file => onChange(file, "unlink"))
 
       function onChange(file: string, kind: "change" | "add" | "unlink") {
-        if (file === opts.config.configPath) {
+        if (restartFiles.has(file)) {
           server.restart()
           return
         }
@@ -196,6 +215,53 @@ function syncSource(
   if (existsSync(source)) cpSync(source, dest, { recursive: true, force: true })
 }
 
+// A running server keeps the livemark it started with: an in-process restart cannot
+// reload the package's own modules, so an upgrade is reported instead.
+function watchInstalledVersion(server: ViteDevServer, root: string) {
+  const packageDir = findInstalledPackageDir(root)
+  if (!packageDir) return
+  // Vite's watcher ignores node_modules, so the lockfile is what signals an install.
+  const projectDir = dirname(dirname(packageDir))
+  const manifest = join(packageDir, "package.json")
+  const watched = LOCKFILES.map(name => join(projectDir, name))
+  server.watcher.add(watched)
+  let timer: NodeJS.Timeout | undefined
+  server.watcher.on("all", (_, file) => {
+    if (!watched.includes(file)) return
+    clearTimeout(timer)
+    // Let the package manager finish relinking after it writes the lockfile.
+    timer = setTimeout(reportUpgrade, 1000)
+  })
+
+  function reportUpgrade() {
+    const version = readPackageVersion(manifest)
+    if (!version || version === packageJson.version) return
+    server.config.logger.warn(
+      `livemark ${packageJson.version} → ${version} installed; restart the dev server to use it`,
+      { timestamp: true },
+    )
+  }
+}
+
+function findInstalledPackageDir(root: string) {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const packageDir = join(dir, "node_modules", packageJson.name)
+    if (existsSync(packageDir)) return packageDir
+    if (dirname(dir) === dir) return undefined
+  }
+}
+
+function readPackageVersion(manifest: string) {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(manifest, "utf8"))
+    return isObject(parsed) && typeof parsed.version === "string"
+      ? parsed.version
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** Resolve livemark.config.ts's `vite` field — either a config object
  *  or a function `(env) => config` (matching Vite's own `defineConfig`).
  *  Schema stores it as `unknown`; typing for the consumer's editor

package/source/styles/markdown.css

@@ -44,6 +44,11 @@
     @apply px-4;
   }
 
+  /* `code` is a flex column, where an empty line span collapses to no height */
+  .prose pre code .line:empty::before {
+    content: " ";
+  }
+
   .prose pre code .line[data-highlighted] {
     @apply bg-primary/10;
   }

package/source/vite.config.ts

@@ -1,4 +1,3 @@
-import contentCollections from "@content-collections/vite"
 import tailwind from "@tailwindcss/vite"
 import { devtools } from "@tanstack/devtools-vite"
 import { tanstackStart } from "@tanstack/react-start/plugin/vite"
@@ -7,6 +6,7 @@ import { defineConfig } from "vite"
 import svgr from "vite-plugin-svgr"
 import { loadConfig } from "./actions/config/load.ts"
 import { agents } from "./plugins/vite-agents.ts"
+import { content } from "./plugins/vite-content.ts"
 import { livemark } from "./plugins/vite-livemark.ts"
 import { robots } from "./plugins/vite-robots.ts"
 
@@ -34,7 +34,7 @@ export default defineConfig({
     // any browser error back and forth forever.
     devtools({ consolePiping: { enabled: false } }),
     tailwind(),
-    contentCollections({ configPath: "content-collections.ts" }),
+    content({ configPath: "content-collections.ts", contentDir: config.root }),
     tanstackStart({
       srcDirectory: ".",
       // Seed path must match what the crawler produces (router-emitted