livemark 0.25.0 → 0.26.0

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")
+  })
+})

package/source/hooks/hydrated.ts

@@ -0,0 +1,18 @@
+import { useSyncExternalStore } from "react"
+
+/** False during SSR and the hydrating render, true from the first client render on. */
+export function useHydrated() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}
+
+function subscribe() {
+  return () => {}
+}
+
+function getSnapshot() {
+  return true
+}
+
+function getServerSnapshot() {
+  return false
+}

package/source/index.ts

@@ -1 +1,2 @@
 export { defineConfig } from "./actions/config/define.ts"
+export type { RootHead } from "./helpers/head.ts"

package/source/models/config.ts

@@ -22,6 +22,15 @@ export type ViteOverride =
  *  resolves it to a string before any runtime sees it. */
 export type Base = string | ((command: "build" | "serve") => string | undefined)
 
+/** Extra site-wide `<head>` tags, appended after Livemark's defaults. A meta tag
+ *  sharing a default's `name` or `property` replaces it. */
+export type Head = z.infer<typeof Head>
+export const Head = z.object({
+  meta: z.array(z.record(z.string(), z.string())).optional(),
+  links: z.array(z.record(z.string(), z.string())).optional(),
+  scripts: z.array(z.record(z.string(), z.string())).optional(),
+})
+
 /**
  * User-provided configuration for Livemark.
  *
@@ -46,6 +55,7 @@ export const UserConfig = z.object({
   logo: z.string().optional(),
   title: z.string().default("Livemark"),
   description: z.string().default("Markdown site generator"),
+  banner: z.string().optional(),
   include: z.union([z.string(), z.array(z.string())]).default("**/*.md"),
   exclude: z.union([z.string(), z.array(z.string())]).optional(),
   codeThemeLight: CodeThemeLight.default("catppuccin-latte"),
@@ -53,6 +63,7 @@ export const UserConfig = z.object({
   links: z.array(Link).optional(),
   sections: z.array(Section).optional(),
   patches: z.array(Patch).optional(),
+  head: Head.optional(),
   // Stored as `unknown` in the schema (zod can't type a Vite UserConfig
   // or a function returning one meaningfully); the public TypeScript
   // surface above lifts it back to ViteOverride for editor support.
@@ -69,8 +80,10 @@ export const WebsiteConfig = UserConfig.pick({
   site: true,
   favicon: true,
   logo: true,
+  banner: true,
   links: true,
   sections: true,
+  head: true,
 }).extend({
   base: z.string().optional(),
 })

package/source/models/section.ts

@@ -62,3 +62,6 @@ export const Section = z.preprocess(
     CustomSection,
   ]),
 )
+
+/** A section that owns a URL prefix — every type except `custom`. */
+export type RoutedSection = Exclude<Section, CustomSection>