livemark 0.25.0 → 0.27.0

package/source/helpers/llms.ts

@@ -0,0 +1,109 @@
+import type { Config } from "../models/config.ts"
+import type { RoutedSection } from "../models/section.ts"
+import {
+  buildArticleTree,
+  compareArticleDate,
+  compareArticleOrder,
+  flattenArticleTree,
+} from "./article.ts"
+import { partitionBySection } from "./section.ts"
+
+/** The slice of a built article that agent-facing files are rendered from. */
+export interface LlmsArticle {
+  path: string
+  title: string
+  description?: string
+  order?: number
+  date?: string
+}
+
+/** Render `llms.txt`: the site title and description, then one Markdown link
+ *  per article twin, grouped under each routed section in sidebar order. */
+export function renderLlmsText(props: {
+  config: Pick<Config, "title" | "description" | "site" | "base" | "sections">
+  articles: LlmsArticle[]
+}) {
+  const lines = [`# ${props.config.title}`, "", `> ${props.config.description}`]
+  for (const group of groupArticles(props)) {
+    lines.push("", `## ${group.title}`, "", ...renderLinks(props.config, group.articles))
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** Render the Markdown twin of a section's index page (a blog or changelog
+ *  listing), which has no article of its own: links to the section's articles. */
+export function renderSectionIndex(props: {
+  config: Pick<Config, "site" | "base" | "sections">
+  section: RoutedSection
+  articles: LlmsArticle[]
+}) {
+  const group = groupArticles(props).find(g => g.prefix === props.section.prefix)
+  const lines = [
+    `# ${props.section.title}`,
+    "",
+    ...renderLinks(props.config, group?.articles ?? []),
+  ]
+  return `${lines.join("\n")}\n`
+}
+
+/** Render the Markdown twin of an article: its title and description as the
+ *  rendered page shows them, then the body without its own leading h1. */
+export function renderMarkdownTwin(props: { article: LlmsArticle; content: string }) {
+  const article = props.article
+  const parts = [`# ${article.title}`]
+  if (article.description) parts.push(`> ${article.description}`)
+  parts.push(stripLeadingH1(props.content).trim())
+  return `${parts.join("\n\n")}\n`
+}
+
+/** Path of an article's Markdown twin inside the build output (no base). */
+export function buildTwinFileName(path: string) {
+  return `${path.replace(/^\//, "")}index.md`
+}
+
+/** Drop a leading h1 so a title set by frontmatter or a patch is not shown twice */
+export function stripLeadingH1(content: string) {
+  return content.replace(/^[ \t]*#\s+[^\n]*\n+/, "")
+}
+
+function buildTwinUrl(config: Pick<Config, "site" | "base">, path: string) {
+  const host = config.site?.replace(/\/+$/, "") ?? ""
+  return `${host}${config.base ?? ""}${path}index.md`
+}
+
+function groupArticles(props: {
+  config: Pick<Config, "sections">
+  articles: LlmsArticle[]
+}) {
+  const sections =
+    props.config.sections?.filter((s): s is RoutedSection => s.type !== "custom") ?? []
+  const buckets = partitionBySection(
+    [...props.articles].sort(compareArticleOrder),
+    sections,
+  )
+  const groups = [
+    ...sections.map(s => ({
+      prefix: s.prefix,
+      title: s.title,
+      dated: s.type !== "article",
+    })),
+    { prefix: "__default__", title: sections.length ? "Other" : "Pages", dated: false },
+  ]
+  return groups.flatMap(group => {
+    const bucket = buckets.get(group.prefix)
+    if (!bucket?.length) return []
+    const articles = group.dated
+      ? [...bucket].sort(compareArticleDate)
+      : flattenArticleTree(buildArticleTree(bucket)).flatMap(
+          path => bucket.find(a => a.path === path) ?? [],
+        )
+    return [{ prefix: group.prefix, title: group.title, articles }]
+  })
+}
+
+function renderLinks(config: Pick<Config, "site" | "base">, articles: LlmsArticle[]) {
+  return articles.map(article => {
+    const link = `[${article.title}](${buildTwinUrl(config, article.path)})`
+    return article.description ? `- ${link}: ${article.description}` : `- ${link}`
+  })
+}

package/source/helpers/llms.unit.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vite-plus/test"
+import type { RoutedSection } from "../models/section.ts"
+import {
+  buildTwinFileName,
+  renderLlmsText,
+  renderMarkdownTwin,
+  renderSectionIndex,
+} from "./llms.ts"
+
+const config = { title: "Docs", description: "Blurb" }
+
+describe("renderLlmsText", () => {
+  it("lists articles in sidebar order under a single heading without sections", () => {
+    const text = renderLlmsText({
+      config,
+      articles: [
+        { path: "/guide/", title: "Guide", order: 2 },
+        { path: "/intro/", title: "Intro", description: "Start here", order: 1 },
+        { path: "/guide/deep/", title: "Deep" },
+      ],
+    })
+    expect(text).toBe(
+      [
+        "# Docs",
+        "",
+        "> Blurb",
+        "",
+        "## Pages",
+        "",
+        "- [Intro](/intro/index.md): Start here",
+        "- [Guide](/guide/index.md)",
+        "- [Deep](/guide/deep/index.md)",
+        "",
+      ].join("\n"),
+    )
+  })
+
+  it("groups by routed section, newest first in a blog, with absolute urls", () => {
+    const text = renderLlmsText({
+      config: {
+        ...config,
+        site: "https://example.com/",
+        base: "/repo",
+        sections: [
+          { title: "Docs", prefix: "/", type: "article", position: "header" },
+          { title: "Blog", prefix: "/blog/", type: "blog", position: "header" },
+          {
+            title: "GitHub",
+            url: "https://github.com",
+            type: "custom",
+            position: "header",
+          },
+        ],
+      },
+      articles: [
+        { path: "/blog/old/", title: "Old", date: "2026-01-01" },
+        { path: "/intro/", title: "Intro" },
+        { path: "/blog/new/", title: "New", date: "2026-02-01" },
+      ],
+    })
+    expect(text).toContain(
+      [
+        "## Docs",
+        "",
+        "- [Intro](https://example.com/repo/intro/index.md)",
+        "",
+        "## Blog",
+        "",
+        "- [New](https://example.com/repo/blog/new/index.md)",
+        "- [Old](https://example.com/repo/blog/old/index.md)",
+      ].join("\n"),
+    )
+    expect(text).not.toContain("GitHub")
+  })
+})
+
+describe("renderSectionIndex", () => {
+  it("lists only the section's articles, newest first", () => {
+    const blog: RoutedSection = {
+      title: "Blog",
+      prefix: "/blog/",
+      type: "blog",
+      position: "header",
+    }
+    const text = renderSectionIndex({
+      config: { sections: [blog] },
+      section: blog,
+      articles: [
+        { path: "/intro/", title: "Intro" },
+        { path: "/blog/old/", title: "Old", date: "2026-01-01" },
+        { path: "/blog/new/", title: "New", date: "2026-02-01", description: "Fresh" },
+      ],
+    })
+    expect(text).toBe(
+      "# Blog\n\n- [New](/blog/new/index.md): Fresh\n- [Old](/blog/old/index.md)\n",
+    )
+  })
+})
+
+describe("renderMarkdownTwin", () => {
+  it("leads with the title and description instead of the body's own h1", () => {
+    const twin = renderMarkdownTwin({
+      article: { path: "/intro/", title: "Introduction", description: "Start here" },
+      content: "# Livemark\n\nBody text\n",
+    })
+    expect(twin).toBe("# Introduction\n\n> Start here\n\nBody text\n")
+  })
+})
+
+describe("buildTwinFileName", () => {
+  it("places the twin beside the page's index.html", () => {
+    expect(buildTwinFileName("/")).toBe("index.md")
+    expect(buildTwinFileName("/guide/deep/")).toBe("guide/deep/index.md")
+  })
+})

package/source/helpers/nav-items.tsx

@@ -0,0 +1,102 @@
+import { config } from "livemark:virtual"
+import { Link, useLocation } from "@tanstack/react-router"
+import {
+  sectionFirstArticle,
+  sectionFlatArticles,
+  sortedArticles,
+} from "../content/article.ts"
+import { DynamicIcon } from "./dynamic-icon.tsx"
+import { prefixUrl } from "./prefix-url.ts"
+import { customSectionActive } from "./section.ts"
+
+export type NavItem = {
+  key: string
+  title: string
+  icon?: string
+  suffix?: string
+  active: boolean
+  href?: string
+  target?: string
+}
+
+export function useNavItems(activePrefix?: string) {
+  const pathname = useLocation({ select: l => l.pathname })
+  const sections = config.sections ?? []
+  const items: NavItem[] = sections
+    .filter(section => section.position === "header")
+    .map(section => {
+      if (section.type === "custom") {
+        return {
+          key: section.url,
+          title: section.title,
+          icon: section.icon,
+          active: customSectionActive(section.url, pathname),
+          href: section.url,
+        }
+      }
+      const suffix =
+        section.type === "changelog" && section.version
+          ? sortedArticles.find(
+              a => a.path === sectionFlatArticles.get(section.prefix)?.[0],
+            )?.title
+          : undefined
+      return {
+        key: section.prefix,
+        title: section.title,
+        icon: section.icon,
+        suffix,
+        active: activePrefix === section.prefix,
+        target:
+          section.type === "blog" || section.type === "changelog"
+            ? section.prefix
+            : sectionFirstArticle.get(section.prefix),
+      }
+    })
+  if (!sections.length) {
+    items.push({ key: "/", title: "Docs", active: true, target: "/" })
+  }
+  for (const link of config.links ?? []) {
+    if (link.position !== "header") continue
+    if (link.prefix && link.prefix !== activePrefix) continue
+    items.push({
+      key: link.url,
+      title: link.title,
+      icon: link.icon,
+      active: false,
+      href: link.url,
+    })
+  }
+  return items
+}
+
+export function renderNavAnchor(item: NavItem, className?: string) {
+  const children = (
+    <>
+      {item.icon && <DynamicIcon name={item.icon} className="size-3.5" />}
+      <span>
+        {item.title}
+        {item.suffix && <span className="opacity-80"> ({item.suffix})</span>}
+      </span>
+    </>
+  )
+  if (item.href) {
+    return (
+      <a href={prefixUrl(item.href, config.base)} className={className}>
+        {children}
+      </a>
+    )
+  }
+  return (
+    <Link
+      to={item.target === "/" ? "/" : "/$"}
+      params={item.target && item.target !== "/" ? splatFor(item.target) : {}}
+      className={className}
+    >
+      {children}
+    </Link>
+  )
+}
+
+function splatFor(pathname: string) {
+  return { _splat: pathname.replace(/^\/|\/$/g, "") }
+}

package/source/helpers/render-inline-markdown.ts

@@ -0,0 +1,44 @@
+import rehypeStringify from "rehype-stringify"
+import remarkGfm from "remark-gfm"
+import remarkParse from "remark-parse"
+import remarkRehype from "remark-rehype"
+import { unified } from "unified"
+import { visit } from "unist-util-visit"
+import { prefixUrl } from "./prefix-url.ts"
+
+interface HastNode {
+  type: string
+  tagName?: string
+  properties?: Record<string, unknown>
+  children?: HastNode[]
+}
+
+export function renderInlineMarkdown(markdown: string, base: string | undefined) {
+  const html = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(() => (tree: HastNode) => rewriteLinks(tree, base))
+    .use(() => unwrapParagraphs)
+    .use(rehypeStringify)
+    .processSync(markdown)
+  return String(html).trim()
+}
+
+function rewriteLinks(tree: HastNode, base: string | undefined) {
+  visit(tree, "element", (node: HastNode) => {
+    if (node.tagName !== "a" || typeof node.properties?.href !== "string") return
+    const href = node.properties.href
+    node.properties.href = prefixUrl(href, base)
+    if (/^https?:\/\//.test(href)) {
+      node.properties.target = "_blank"
+      node.properties.rel = ["noopener", "noreferrer"]
+    }
+  })
+}
+
+function unwrapParagraphs(tree: HastNode) {
+  tree.children = (tree.children ?? []).flatMap(child =>
+    child.type === "element" && child.tagName === "p" ? (child.children ?? []) : [child],
+  )
+}

package/source/helpers/render-inline-markdown.unit.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vite-plus/test"
+import { renderInlineMarkdown } from "./render-inline-markdown.ts"
+
+describe("renderInlineMarkdown", () => {
+  it("should render plain text without a paragraph", () => {
+    expect(renderInlineMarkdown("Hello world", undefined)).toBe("Hello world")
+  })
+
+  it("should render bold, emphasis and code", () => {
+    expect(renderInlineMarkdown("**a** _b_ `c`", undefined)).toBe(
+      "<strong>a</strong> <em>b</em> <code>c</code>",
+    )
+  })
+
+  it("should open absolute links in a new tab", () => {
+    expect(renderInlineMarkdown("[x](https://example.com)", undefined)).toBe(
+      '<a href="https://example.com" target="_blank" rel="noopener noreferrer">x</a>',
+    )
+  })
+
+  it("should prefix root-relative links with the base", () => {
+    expect(renderInlineMarkdown("[x](/blog/)", "/repo")).toBe(
+      '<a href="/repo/blog/">x</a>',
+    )
+  })
+
+  it("should drop raw HTML tags", () => {
+    expect(renderInlineMarkdown("a <b onclick=x>c</b>", undefined)).toBe("a c")
+  })
+})

package/source/helpers/search-highlight.ts

@@ -0,0 +1,73 @@
+import { useEffect, type RefObject } from "react"
+
+const HIGHLIGHT_NAME = "search-match"
+
+/** Build a case-insensitive pattern matching each word of a search query */
+export function buildHighlightPattern(query: string) {
+  const words = [...new Set(query.toLowerCase().split(/\s+/))]
+    .filter(word => word.length >= 2)
+    .sort((a, b) => b.length - a.length)
+    .map(word => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+  if (!words.length) return undefined
+  return new RegExp(words.join("|"), "gi")
+}
+
+/** Find the `[start, end]` offsets of every pattern match in a text */
+export function findTextMatches(text: string, pattern: RegExp) {
+  return [...text.matchAll(pattern)].map(
+    match => [match.index, match.index + match[0].length] as const,
+  )
+}
+
+/** Highlight search query matches under `root` and scroll to the first visible one;
+ *  `page` re-runs it when the same query lands on another page */
+export function useSearchHighlight(
+  root: RefObject<HTMLElement | null>,
+  page: string,
+  query?: string,
+) {
+  useEffect(() => {
+    const pattern = query ? buildHighlightPattern(query) : undefined
+    if (!pattern || !root.current || typeof CSS === "undefined" || !CSS.highlights) return
+
+    const ranges = collectMatchRanges(root.current, pattern)
+    CSS.highlights.set(HIGHLIGHT_NAME, new Highlight(...ranges))
+
+    // An explicit anchor in the URL wins over the first match. The frame delay lets
+    // the router's scroll restoration, which resets to the top, run first.
+    const frame = window.location.hash
+      ? undefined
+      : requestAnimationFrame(() => scrollToFirstVisible(ranges))
+
+    return () => {
+      if (frame !== undefined) cancelAnimationFrame(frame)
+      CSS.highlights.delete(HIGHLIGHT_NAME)
+    }
+  }, [root, page, query])
+}
+
+function collectMatchRanges(root: HTMLElement, pattern: RegExp) {
+  const ranges: Range[] = []
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode: node =>
+      node.parentElement?.closest("pre, script, style, svg, textarea")
+        ? NodeFilter.FILTER_REJECT
+        : NodeFilter.FILTER_ACCEPT,
+  })
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    for (const [start, end] of findTextMatches(node.textContent ?? "", pattern)) {
+      const range = new Range()
+      range.setStart(node, start)
+      range.setEnd(node, end)
+      ranges.push(range)
+    }
+  }
+  return ranges
+}
+
+function scrollToFirstVisible(ranges: Range[]) {
+  const first = ranges.find(range =>
+    range.startContainer.parentElement?.checkVisibility(),
+  )
+  first?.startContainer.parentElement?.scrollIntoView({ block: "center" })
+}

package/source/helpers/search-highlight.unit.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vite-plus/test"
+import { buildHighlightPattern, findTextMatches } from "./search-highlight.ts"
+
+describe("buildHighlightPattern", () => {
+  it("should return undefined for an empty query", () => {
+    expect(buildHighlightPattern("   ")).toBeUndefined()
+  })
+
+  it("should drop single-character words", () => {
+    expect(buildHighlightPattern("a b")).toBeUndefined()
+    expect(buildHighlightPattern("a config")?.source).toBe("config")
+  })
+
+  it("should put longer words first and dedupe case-insensitively", () => {
+    expect(buildHighlightPattern("Side sidebar side")?.source).toBe("sidebar|side")
+  })
+
+  it("should escape regex syntax", () => {
+    expect(buildHighlightPattern("c++ (x)")?.source).toBe("c\\+\\+|\\(x\\)")
+  })
+})
+
+describe("findTextMatches", () => {
+  it("should find every word case-insensitively", () => {
+    const pattern = buildHighlightPattern("search config")
+    expect(pattern && findTextMatches("Search the Config, search!", pattern)).toEqual([
+      [0, 6],
+      [11, 17],
+      [19, 25],
+    ])
+  })
+
+  it("should prefer the longest word at a shared position", () => {
+    const pattern = buildHighlightPattern("side sidebar")
+    expect(pattern && findTextMatches("the sidebar", pattern)).toEqual([[4, 11]])
+  })
+
+  it("should return no matches when nothing matches", () => {
+    const pattern = buildHighlightPattern("orama")
+    expect(pattern && findTextMatches("nothing here", pattern)).toEqual([])
+  })
+})

package/source/helpers/target-export.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path"
+
+/**
+ * Map a `livemark/<subpath>` import onto the target copy its `exports` entry names, so
+ * escapes importing Livemark modules reach other escapes, not the package originals.
+ */
+export function resolveTargetExport(props: {
+  id: string
+  targetDir: string
+  exports: Record<string, string>
+}) {
+  const queryIndex = props.id.indexOf("?")
+  const specifier = queryIndex === -1 ? props.id : props.id.slice(0, queryIndex)
+  const query = queryIndex === -1 ? "" : props.id.slice(queryIndex)
+  if (!specifier.startsWith("livemark/")) return undefined
+
+  const subpath = `./${specifier.slice("livemark/".length)}`
+  for (const [key, value] of Object.entries(props.exports)) {
+    const [prefix, suffix] = key.split("*")
+    if (suffix === undefined || !prefix || !value.startsWith("./source/")) continue
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue
+    const name = subpath.slice(prefix.length, subpath.length - suffix.length)
+    return (
+      join(props.targetDir, value.slice("./source/".length).replace("*", name)) + query
+    )
+  }
+  return undefined
+}

package/source/helpers/target-export.unit.ts

@@ -0,0 +1,37 @@
+import { join } from "node:path"
+import { describe, expect, it } from "vite-plus/test"
+import packageJson from "../../package.json" with { type: "json" }
+import { resolveTargetExport } from "./target-export.ts"
+
+const targetDir = "/project/.livemark/.target"
+
+function resolveId(id: string) {
+  return resolveTargetExport({ id, targetDir, exports: packageJson.exports })
+}
+
+describe("resolveTargetExport", () => {
+  it("maps each source subpath export into the target", () => {
+    expect(resolveId("livemark/components/Footer")).toBe(
+      join(targetDir, "components/Footer.tsx"),
+    )
+    expect(resolveId("livemark/elements/button")).toBe(
+      join(targetDir, "elements/button.tsx"),
+    )
+    expect(resolveId("livemark/hooks/in-view")).toBe(join(targetDir, "hooks/in-view.ts"))
+    expect(resolveId("livemark/styles/general")).toBe(
+      join(targetDir, "styles/general.css"),
+    )
+  })
+
+  it("keeps the query", () => {
+    expect(resolveId("livemark/styles/general?url")).toBe(
+      `${join(targetDir, "styles/general.css")}?url`,
+    )
+  })
+
+  it("leaves other specifiers alone", () => {
+    expect(resolveId("livemark")).toBeUndefined()
+    expect(resolveId("livemark/unknown/thing")).toBeUndefined()
+    expect(resolveId("react")).toBeUndefined()
+  })
+})

package/source/helpers/theme.ts

@@ -1,10 +1,12 @@
 const STORAGE_KEY = "livemark-theme"
+const DARK_QUERY = "(prefers-color-scheme: dark)"
 
 export type Theme = "light" | "dark"
+export type ThemePref = Theme | "system"
 
-export function detectClientTheme(): Theme {
-  const stored = localStorage.getItem(STORAGE_KEY) as Theme | null
-  return stored || "light"
+export function resolveTheme(pref: ThemePref, prefersDark: boolean): Theme {
+  if (pref === "system") return prefersDark ? "dark" : "light"
+  return pref
 }
 
 export function activateTheme(theme: Theme) {
@@ -21,7 +23,39 @@ export function getCurrentTheme(): Theme {
     : "light"
 }
 
-export function setTheme(theme: Theme) {
-  activateTheme(theme)
-  localStorage.setItem(STORAGE_KEY, theme)
+// Mirrors `buildThemeScript`: anything but an explicit light or dark follows the OS.
+export function getThemePref(): ThemePref {
+  let stored: string | null = null
+  try {
+    stored = localStorage.getItem(STORAGE_KEY)
+  } catch {}
+  return stored === "light" || stored === "dark" ? stored : "system"
+}
+
+export function setTheme(pref: ThemePref) {
+  applyThemePref(pref)
+  try {
+    localStorage.setItem(STORAGE_KEY, pref)
+  } catch {}
+}
+
+// Returns the OS listener's cleanup, so an effect StrictMode runs twice keeps one.
+export function startTheme() {
+  const query = matchMedia(DARK_QUERY)
+  const handleChange = () => {
+    if (getThemePref() === "system") applyThemePref("system")
+  }
+  applyThemePref(getThemePref())
+  query.addEventListener("change", handleChange)
+  return () => query.removeEventListener("change", handleChange)
+}
+
+// The pre-paint twin of `startTheme`, inlined in <head> so a dark reader never sees
+// the light palette flash before hydration.
+export function buildThemeScript() {
+  return `try{var t=localStorage.getItem(${JSON.stringify(STORAGE_KEY)})}catch(e){}if(t==="dark"||(t!=="light"&&matchMedia(${JSON.stringify(DARK_QUERY)}).matches))document.documentElement.classList.add("dark");`
+}
+
+function applyThemePref(pref: ThemePref) {
+  activateTheme(resolveTheme(pref, matchMedia(DARK_QUERY).matches))
 }

package/source/helpers/theme.unit.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from "vite-plus/test"
+import { buildThemeScript, resolveTheme } from "./theme.ts"
+
+function runThemeScript(stored: string | null, prefersDark: boolean) {
+  const classes = new Set<string>()
+  vi.stubGlobal("localStorage", { getItem: () => stored })
+  vi.stubGlobal("matchMedia", () => ({ matches: prefersDark }))
+  vi.stubGlobal("document", {
+    documentElement: { classList: { add: (name: string) => classes.add(name) } },
+  })
+  new Function(buildThemeScript())()
+  vi.unstubAllGlobals()
+  return classes.has("dark") ? "dark" : "light"
+}
+
+describe("buildThemeScript", () => {
+  it.each([
+    ["light", false],
+    ["light", true],
+    ["dark", false],
+    ["dark", true],
+    ["system", false],
+    ["system", true],
+  ] as const)("paints what resolveTheme(%s, prefersDark %s) does", (pref, dark) => {
+    expect(runThemeScript(pref, dark)).toBe(resolveTheme(pref, dark))
+  })
+
+  it.each([null, "", "auto"])("follows the OS for a stored %j", stored => {
+    expect(runThemeScript(stored, true)).toBe("dark")
+    expect(runThemeScript(stored, false)).toBe("light")
+  })
+})