livemark 0.2.0 → 0.7.0

package/build/website/helpers/article.ts

@@ -0,0 +1,90 @@
+import type { ArticleGroup, ArticleNode } from "../models/article.ts"
+
+/** Build a tree from a flat sorted list of articles based on path hierarchy */
+export function buildArticleTree(
+  articles: {
+    path: string
+    title: string
+    label?: string
+    icon: string
+  }[],
+) {
+  const nodeMap = new Map<string, ArticleNode>()
+
+  for (const article of articles) {
+    nodeMap.set(article.path, {
+      path: article.path,
+      title: article.title,
+      label: article.label,
+      icon: article.icon,
+      children: [],
+    })
+  }
+
+  const roots: ArticleNode[] = []
+
+  for (const article of articles) {
+    const node = nodeMap.get(article.path)
+    if (!node) continue
+    const trimmed = article.path.replace(/\/$/, "")
+    const lastSlash = trimmed.lastIndexOf("/")
+    const parentPath = lastSlash > 0 ? `${trimmed.slice(0, lastSlash)}/` : ""
+    const parent = parentPath ? nodeMap.get(parentPath) : undefined
+
+    if (parent) {
+      parent.children.push(node)
+    } else {
+      roots.push(node)
+    }
+  }
+
+  return roots
+}
+
+/**
+ * Partition root nodes into sidebar sections.
+ *
+ * Walks root nodes in sort order. A root whose article has a `group` field
+ * opens a new section; subsequent roots without `group` append to the current
+ * section. Roots before the first `group` field land in a single leading
+ * section with `name: undefined` (rendered without a label).
+ *
+ * `group` on non-root articles is ignored — only roots gate section boundaries.
+ */
+export function groupArticleTree(
+  tree: ArticleNode[],
+  articles: { path: string; group?: string }[],
+): ArticleGroup[] {
+  const groupByPathname = new Map<string, string | undefined>()
+  for (const article of articles) {
+    groupByPathname.set(article.path, article.group)
+  }
+
+  const sections: ArticleGroup[] = []
+  let current: ArticleGroup | undefined
+
+  for (const node of tree) {
+    const group = groupByPathname.get(node.path)
+    if (group) {
+      current = { name: group, nodes: [node] }
+      sections.push(current)
+    } else if (current) {
+      current.nodes.push(node)
+    } else {
+      current = { name: undefined, nodes: [node] }
+      sections.push(current)
+    }
+  }
+
+  return sections
+}
+
+/** Depth-first flatten of an article tree into a list of paths */
+export function flattenArticleTree(nodes: ArticleNode[]) {
+  const result: string[] = []
+  for (const node of nodes) {
+    result.push(node.path)
+    result.push(...flattenArticleTree(node.children))
+  }
+  return result
+}

package/build/website/helpers/changelog-source.ts

@@ -0,0 +1,16 @@
+/** Returns true if a changelog source string is a GitHub repo URL */
+export function isGitHubUrl(source: string) {
+  return /^(https?:\/\/)?(www\.)?github\.com\//.test(source)
+}
+
+/** Extract `{ owner, repo }` from a GitHub URL. Returns undefined if unparseable */
+export function parseGitHubRepo(source: string) {
+  const match = source.match(
+    /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/]+)\/([^/#?]+)/,
+  )
+  if (!match) return undefined
+  const owner = match[1]
+  const repo = match[2]?.replace(/\.git$/, "")
+  if (!owner || !repo) return undefined
+  return { owner, repo }
+}

package/build/website/helpers/changelog-source.unit.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vite-plus/test"
+import { isGitHubUrl, parseGitHubRepo } from "./changelog-source.ts"
+
+describe("isGitHubUrl", () => {
+  it("recognizes https github URLs", () => {
+    expect(isGitHubUrl("https://github.com/foo/bar")).toBe(true)
+  })
+
+  it("recognizes bare github.com URLs", () => {
+    expect(isGitHubUrl("github.com/foo/bar")).toBe(true)
+  })
+
+  it("rejects local paths", () => {
+    expect(isGitHubUrl("CHANGELOG.md")).toBe(false)
+    expect(isGitHubUrl("./CHANGELOG.md")).toBe(false)
+    expect(isGitHubUrl("docs/CHANGELOG.md")).toBe(false)
+  })
+})
+
+describe("parseGitHubRepo", () => {
+  it("extracts owner and repo from https URL", () => {
+    expect(parseGitHubRepo("https://github.com/datisthq/livemark")).toEqual({
+      owner: "datisthq",
+      repo: "livemark",
+    })
+  })
+
+  it("strips .git suffix", () => {
+    expect(parseGitHubRepo("https://github.com/foo/bar.git")).toEqual({
+      owner: "foo",
+      repo: "bar",
+    })
+  })
+
+  it("returns undefined for non-github input", () => {
+    expect(parseGitHubRepo("CHANGELOG.md")).toBeUndefined()
+  })
+})

package/build/website/helpers/dynamic-icon-resolver.tsx

@@ -0,0 +1,19 @@
+import { icons } from "lucide-react"
+
+function toPascalCase(name: string) {
+  return name
+    .split("-")
+    .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("")
+}
+
+/** Resolves a Lucide icon by kebab-case name from the full registry */
+export default function DynamicIconResolver(props: {
+  name: string
+  className?: string
+}) {
+  const key = toPascalCase(props.name)
+  if (!(key in icons)) return null
+  const Icon = icons[key as keyof typeof icons]
+  return <Icon className={props.className} />
+}

package/build/website/helpers/dynamic-icon.tsx

@@ -0,0 +1,12 @@
+import { Suspense, lazy } from "react"
+
+const Resolver = lazy(() => import("./dynamic-icon-resolver.tsx"))
+
+/** Lazily loads and renders a Lucide icon by kebab-case name */
+export function DynamicIcon(props: { name: string; className?: string }) {
+  return (
+    <Suspense>
+      <Resolver {...props} />
+    </Suspense>
+  )
+}

package/build/website/helpers/favicon.ts

@@ -0,0 +1,7 @@
+/** Derive the MIME type for a favicon from its file extension */
+export function faviconType(href: string) {
+  if (href.endsWith(".svg")) return "image/svg+xml"
+  if (href.endsWith(".png")) return "image/png"
+  if (href.endsWith(".ico")) return "image/x-icon"
+  return undefined
+}

package/build/website/helpers/model.ts

@@ -0,0 +1,4 @@
+import { z } from "zod"
+
+/** Zod schema for a non-empty string (rejects ""). */
+export const nonEmptyString = z.string().min(1)

package/build/website/helpers/resolve-asset-path.ts

@@ -0,0 +1,9 @@
+import { dirname, relative, resolve } from "node:path"
+
+/** Resolve a relative asset path to an absolute URL serveable by Vite */
+export function resolveAssetPath(url: string, filePath: string, root: string) {
+  if (url.startsWith("http") || url.startsWith("/") || url.startsWith("data:"))
+    return url
+  const absolute = resolve(dirname(filePath), url)
+  return "/" + relative(root, absolute)
+}

package/build/website/helpers/resolve-includes.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs"
+import { dirname, extname, resolve } from "node:path"
+
+const INCLUDE_RE = /^::include\{(.+)\}$/
+const FRONTMATTER_RE = /^---\n[\s\S]*?\n---\n?/
+const FENCE_RE = /^(`{3,}|~{3,})/
+
+const extToLang: Record<string, string> = {
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".js": "javascript",
+  ".jsx": "jsx",
+  ".py": "python",
+  ".rs": "rust",
+  ".go": "go",
+  ".rb": "ruby",
+  ".java": "java",
+  ".kt": "kotlin",
+  ".swift": "swift",
+  ".c": "c",
+  ".cpp": "cpp",
+  ".h": "c",
+  ".cs": "csharp",
+  ".css": "css",
+  ".scss": "scss",
+  ".html": "html",
+  ".json": "json",
+  ".yaml": "yaml",
+  ".yml": "yaml",
+  ".toml": "toml",
+  ".xml": "xml",
+  ".sql": "sql",
+  ".sh": "bash",
+  ".bash": "bash",
+  ".zsh": "zsh",
+  ".fish": "fish",
+  ".ps1": "powershell",
+  ".dockerfile": "dockerfile",
+  ".graphql": "graphql",
+  ".proto": "protobuf",
+  ".lua": "lua",
+  ".php": "php",
+  ".r": "r",
+  ".zig": "zig",
+  ".ex": "elixir",
+  ".exs": "elixir",
+}
+
+function parseAttributes(raw: string): Record<string, string> {
+  const attrs: Record<string, string> = {}
+  const re = /(\w+)="([^"]+)"/g
+  let m: RegExpExecArray | null = null
+  while ((m = re.exec(raw)) !== null) {
+    attrs[m[1]!] = m[2]!
+  }
+  return attrs
+}
+
+function resolveDirective(
+  rawAttrs: string,
+  fileDir: string,
+  depth: number,
+): string | undefined {
+  const attrs = parseAttributes(rawAttrs)
+  const file = attrs.file
+  if (!file) return undefined
+
+  const absolutePath = resolve(fileDir, file)
+  try {
+    let included = readFileSync(absolutePath, "utf-8")
+
+    const ext = extname(file).toLowerCase()
+    const lang = extToLang[ext]
+
+    if (lang && !file.endsWith(".md")) {
+      const filename = file.split("/").pop()!
+      const title = `title="${filename}"`
+      const meta = attrs.meta ? ` ${attrs.meta}` : ""
+      return (
+        "```" + lang + " " + title + meta + "\n" + included.trimEnd() + "\n```"
+      )
+    }
+
+    included = included.replace(FRONTMATTER_RE, "")
+    return resolveIncludes(included.trim(), absolutePath, depth + 1)
+  } catch {
+    return undefined
+  }
+}
+
+/** Resolves ::include{file="..."} directives by replacing them with referenced file contents */
+export function resolveIncludes(
+  content: string,
+  filePath: string,
+  depth = 0,
+): string {
+  if (depth > 5) return content
+
+  const fileDir = dirname(filePath)
+  const lines = content.split("\n")
+  const result: string[] = []
+  let fenceMarker: string | undefined
+
+  for (const line of lines) {
+    const fenceMatch = FENCE_RE.exec(line)
+    if (fenceMatch) {
+      if (!fenceMarker) {
+        fenceMarker = fenceMatch[1]!
+      } else if (line.startsWith(fenceMarker)) {
+        fenceMarker = undefined
+      }
+      result.push(line)
+      continue
+    }
+
+    if (fenceMarker) {
+      result.push(line)
+      continue
+    }
+
+    const includeMatch = INCLUDE_RE.exec(line)
+    if (includeMatch) {
+      const resolved = resolveDirective(includeMatch[1]!, fileDir, depth)
+      result.push(resolved ?? line)
+    } else {
+      result.push(line)
+    }
+  }
+
+  return result.join("\n")
+}

package/build/website/helpers/resolve-includes.unit.ts

@@ -0,0 +1,126 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { describe, expect, it } from "vite-plus/test"
+import { temporaryDirectory } from "tempy"
+import { resolveIncludes } from "./resolve-includes.ts"
+
+describe("resolveIncludes", () => {
+  it("should replace include directive with file content", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "snippet.md"), "Hello from snippet")
+    const result = resolveIncludes(
+      '::include{file="snippet.md"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Hello from snippet")
+  })
+
+  it("should strip frontmatter from included files", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(
+      join(dir, "snippet.md"),
+      "---\ntitle: Test\n---\nContent here",
+    )
+    const result = resolveIncludes(
+      '::include{file="snippet.md"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Content here")
+  })
+
+  it("should preserve surrounding content", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "snippet.md"), "Included text")
+    const result = resolveIncludes(
+      'Before\n\n::include{file="snippet.md"}\n\nAfter',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Before\n\nIncluded text\n\nAfter")
+  })
+
+  it("should keep directive when file is missing", () => {
+    const result = resolveIncludes(
+      '::include{file="nonexistent.md"}',
+      "/tmp/main.md",
+    )
+    expect(result).toBe('::include{file="nonexistent.md"}')
+  })
+
+  it("should resolve nested includes", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "inner.md"), "Inner content")
+    writeFileSync(join(dir, "outer.md"), '::include{file="inner.md"}')
+    const result = resolveIncludes(
+      '::include{file="outer.md"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Inner content")
+  })
+
+  it("should limit recursion depth", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "recursive.md"), '::include{file="recursive.md"}')
+    const result = resolveIncludes(
+      '::include{file="recursive.md"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe('::include{file="recursive.md"}')
+  })
+
+  it("should resolve relative paths from included file location", () => {
+    const dir = temporaryDirectory()
+    mkdirSync(join(dir, "sub"))
+    writeFileSync(join(dir, "sub", "child.md"), "Child content")
+    writeFileSync(join(dir, "parent.md"), '::include{file="sub/child.md"}')
+    const result = resolveIncludes(
+      '::include{file="parent.md"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Child content")
+  })
+
+  it("should handle multiple includes in one file", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "a.md"), "Alpha")
+    writeFileSync(join(dir, "b.md"), "Beta")
+    const result = resolveIncludes(
+      '::include{file="a.md"}\n\n::include{file="b.md"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Alpha\n\nBeta")
+  })
+
+  it("should wrap code files in fenced blocks", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "example.ts"), 'const x = 1\nconst y = "hello"')
+    const result = resolveIncludes(
+      '::include{file="example.ts"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe(
+      '```typescript title="example.ts"\nconst x = 1\nconst y = "hello"\n```',
+    )
+  })
+
+  it("should pass meta to code fence", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "app.tsx"), "export default function App() {}")
+    const result = resolveIncludes(
+      '::include{file="app.tsx" meta="{1} lineNumbers"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe(
+      '```tsx title="app.tsx" {1} lineNumbers\nexport default function App() {}\n```',
+    )
+  })
+
+  it("should treat unknown extensions as markdown", () => {
+    const dir = temporaryDirectory()
+    writeFileSync(join(dir, "notes.txt"), "Plain text")
+    const result = resolveIncludes(
+      '::include{file="notes.txt"}',
+      join(dir, "main.md"),
+    )
+    expect(result).toBe("Plain text")
+  })
+})

package/build/website/helpers/search-text.ts

@@ -0,0 +1,15 @@
+/** Strip markdown syntax to extract plain searchable text */
+export function extractSearchText(markdown: string) {
+  return markdown
+    .replace(/^---[\s\S]*?---\n*/m, "")
+    .replace(/```[\s\S]*?```/g, "")
+    .replace(/:::\w+[\s\S]*?:::/g, "")
+    .replace(/::\w+(?:\[.*?\])?(?:\{.*?\})?/g, "")
+    .replace(/!\[.*?\]\(.*?\)/g, "")
+    .replace(/\[([^\]]*)\]\(.*?\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/#{1,6}\s*/g, "")
+    .replace(/[*_~`>|]/g, "")
+    .replace(/\n{2,}/g, "\n")
+    .trim()
+}

package/build/website/helpers/section.ts

@@ -0,0 +1,50 @@
+import type { Section } from "../../models/section.ts"
+
+const DEFAULT_ICONS: Record<Section["type"], string> = {
+  article: "book-open",
+  blog: "rss",
+  changelog: "history",
+}
+
+/** Return the section's icon, falling back to a type-based default */
+export function sectionIcon(section: Pick<Section, "icon" | "type">) {
+  return section.icon ?? DEFAULT_ICONS[section.type]
+}
+
+/** Find the section whose prefix is the longest prefix of the article path */
+export function matchSection<S extends { prefix: string }>(
+  articlePath: string,
+  sections: S[],
+): S | undefined {
+  let best: S | undefined
+  let bestLen = 0
+  for (const section of sections) {
+    if (
+      articlePath.startsWith(section.prefix) &&
+      section.prefix.length > bestLen
+    ) {
+      best = section
+      bestLen = section.prefix.length
+    }
+  }
+  return best
+}
+
+/** Split articles into per-section buckets. Unmatched articles go to "__default__" */
+export function partitionBySection<T extends { path: string }>(
+  articles: T[],
+  sections: { prefix: string }[],
+): Map<string, T[]> {
+  const buckets = new Map<string, T[]>()
+  for (const article of articles) {
+    const section = matchSection(article.path, sections)
+    const key = section?.prefix ?? "__default__"
+    const bucket = buckets.get(key)
+    if (bucket) {
+      bucket.push(article)
+    } else {
+      buckets.set(key, [article])
+    }
+  }
+  return buckets
+}

package/build/website/helpers/section.unit.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vite-plus/test"
+import { matchSection, partitionBySection } from "./section.ts"
+
+describe("matchSection", () => {
+  const sections = [
+    { title: "Docs", prefix: "/" },
+    { title: "API", prefix: "/api/" },
+    { title: "API Auth", prefix: "/api/auth/" },
+  ]
+
+  it("should match the most specific prefix", () => {
+    expect(matchSection("/api/auth/login/", sections)?.title).toBe("API Auth")
+  })
+
+  it("should match a less specific prefix when no deeper match", () => {
+    expect(matchSection("/api/users/", sections)?.title).toBe("API")
+  })
+
+  it("should match root section as fallback", () => {
+    expect(matchSection("/getting-started/", sections)?.title).toBe("Docs")
+  })
+
+  it("should return undefined when no section matches", () => {
+    const narrow = [{ title: "API", prefix: "/api/" }]
+    expect(matchSection("/getting-started/", narrow)).toBeUndefined()
+  })
+
+  it("should match a single root section for all articles", () => {
+    const root = [{ title: "Docs", prefix: "/" }]
+    expect(matchSection("/anything/deep/path/", root)?.title).toBe("Docs")
+  })
+})
+
+describe("partitionBySection", () => {
+  const sections = [
+    { title: "Docs", prefix: "/" },
+    { title: "API", prefix: "/api/" },
+  ]
+
+  const articles = [
+    { path: "/getting-started/" },
+    { path: "/guide/" },
+    { path: "/api/users/" },
+    { path: "/api/auth/" },
+  ]
+
+  it("should split articles into section buckets", () => {
+    const result = partitionBySection(articles, sections)
+    expect(result.get("/")?.map(a => a.path)).toEqual([
+      "/getting-started/",
+      "/guide/",
+    ])
+    expect(result.get("/api/")?.map(a => a.path)).toEqual([
+      "/api/users/",
+      "/api/auth/",
+    ])
+  })
+
+  it("should put unmatched articles in __default__ bucket", () => {
+    const narrow = [{ title: "API", prefix: "/api/" }]
+    const result = partitionBySection(articles, narrow)
+    expect(result.get("__default__")?.map(a => a.path)).toEqual([
+      "/getting-started/",
+      "/guide/",
+    ])
+    expect(result.get("/api/")?.map(a => a.path)).toEqual([
+      "/api/users/",
+      "/api/auth/",
+    ])
+  })
+})

package/build/website/helpers/style.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/build/website/helpers/theme.ts

@@ -0,0 +1,27 @@
+const STORAGE_KEY = "livemark-theme"
+
+export type Theme = "light" | "dark"
+
+export function detectClientTheme(): Theme {
+  const stored = localStorage.getItem(STORAGE_KEY) as Theme | null
+  return stored || "light"
+}
+
+export function activateTheme(theme: Theme) {
+  if (theme === "dark") {
+    globalThis.document.documentElement.classList.add("dark")
+  } else {
+    globalThis.document.documentElement.classList.remove("dark")
+  }
+}
+
+export function getCurrentTheme(): Theme {
+  return globalThis.document?.documentElement.classList.contains("dark")
+    ? "dark"
+    : "light"
+}
+
+export function setTheme(theme: Theme) {
+  activateTheme(theme)
+  localStorage.setItem(STORAGE_KEY, theme)
+}

package/build/website/helpers/toc-context.ts

@@ -0,0 +1,10 @@
+import { createContext, useContext } from "react"
+import type { TocItem } from "../models/toc.ts"
+
+/** React context that provides TOC items to inline components */
+export const TocContext = createContext<TocItem[]>([])
+
+/** Consume the TOC items from the nearest TocContext provider */
+export function useTocItems() {
+  return useContext(TocContext)
+}