livemark 0.7.2 → 0.9.0

package/README.md

@@ -1,7 +1,118 @@
 # Livemark
 
-[![Build](https://img.shields.io/github/actions/workflow/status/datisthq/livemark/general.yaml?branch=main)](https://github.com/datisthq/livemark/actions)
-[![Coverage](https://img.shields.io/codecov/c/github/datisthq/livemark/main)](https://codecov.io/gh/datisthq/livemark)
-[![Version](https://img.shields.io/npm/v/livemark)](https://www.npmjs.com/package/livemark)
+Livemark turns plain Markdown into a fast, modern documentation site. Point it at a folder of `.md` files and it gives you a deployable React + Vite site with search, syntax highlighting, blog and changelog sections, dark mode, and a customizable component library — all built in.
 
-Livemark turns your .md files into a fast, modern documentation site — with Shiki, Mermaid, LaTeX, MDX components, blog and changelog sections, all built in. For more information, please read the [project's documentation](https://livemark.dev).
+## What you get
+
+- 📝 **Just write Markdown.** GitHub-flavored Markdown works out of the box, with frontmatter, custom heading IDs, footnotes, definition lists, and gemoji.
+- 🎨 **Beautiful code blocks.** Syntax highlighting via [Shiki](https://shiki.style/) with 100+ languages, dual light/dark themes, line highlights, diffs, and TwoSlash type hints.
+- 📊 **Diagrams and math.** [Mermaid](https://mermaid.js.org/) flowcharts and KaTeX equations, theme-aware, zero config.
+- 🧩 **Rich elements.** Callouts, tabs, file trees, cards, columns, badges, package tabs (npm/pnpm/yarn/bun), embeds (YouTube, SoundCloud), and more — all as Markdown directives or MDX components.
+- 📚 **Sections.** First-class support for docs, blog (with tags + RSS), and changelog (local `CHANGELOG.md` or GitHub releases).
+- 🔍 **Search.** Full-text search powered by [Orama](https://oramasearch.com/), keyboard shortcuts, smart table-of-contents.
+- 🌗 **Themable.** Tailwind v4, shadcn-style primitives, dark mode, and per-file overrides via a `.livemark/` folder.
+- ⚡ **Built on TanStack Start.** SSR, prerendering, sitemap, and routing for free.
+
+## Quick start
+
+You need [Node.js](https://nodejs.org/) 24+ and a package manager (pnpm, npm, yarn, or bun).
+
+### Install
+
+```bash
+npm install livemark
+```
+
+### Configure
+
+Create `livemark.config.ts` at the root of your project:
+
+```ts title="livemark.config.ts"
+import { defineConfig } from "livemark"
+
+export default defineConfig({
+  title: "My docs",
+  description: "Documentation for my project",
+  include: ["docs/**/*.md"],
+})
+```
+
+### Add content
+
+```text title="docs/"
+docs/
+├── getting-started.md
+└── usage.md
+```
+
+Each `.md` file supports frontmatter:
+
+```md title="docs/getting-started.md"
+---
+title: Getting Started
+description: Set up the project in five minutes.
+icon: rocket
+order: 1
+---
+
+# Getting Started
+
+Welcome!
+```
+
+### Run
+
+```bash
+npx livemark start    # dev server with HMR at http://localhost:8000
+npx livemark build    # production build to .livemark/build/
+npx livemark preview  # serve the production build locally
+```
+
+That's the whole loop.
+
+## Project structure
+
+A typical Livemark site:
+
+```text title="my-project/"
+my-project/
+├── livemark.config.ts   # configuration
+├── docs/                # markdown content
+├── blog/                # blog posts (optional)
+├── CHANGELOG.md         # changelog source (optional)
+└── .livemark/           # overrides + build cache (generated)
+```
+
+Anything under `.livemark/components/`, `.livemark/elements/`, or `.livemark/styles/` shadows the Livemark default with the same path — so you can customize components, primitives, and base CSS without forking the package. Run `npx livemark escape <path>` to copy a default into `.livemark/` ready to edit.
+
+## Customization
+
+Livemark is meant to look great with zero configuration and stay out of your way when you need more. Common customizations:
+
+- **Site metadata** — title, description, favicon, logo. See the [Site Metadata guide](https://livemark.dev/customization/site-metadata/).
+- **Sections** — split content into Docs / Blog / Changelog with their own URL prefixes. See [Sections](https://livemark.dev/customization/sections/).
+- **Navigation links** — header and sidebar links to anywhere. See [Navigation Links](https://livemark.dev/customization/navigation-links/).
+- **Syntax themes** — Shiki theme per light/dark. See [Syntax Themes](https://livemark.dev/customization/syntax-themes/).
+- **Content patches** — override a markdown file's frontmatter from `livemark.config.ts` without touching the file. See [Content Patches](https://livemark.dev/customization/content-patches/).
+- **File overrides** — replace any built-in component or stylesheet from your project. See [File Overrides](https://livemark.dev/customization/file-overrides/).
+- **Custom routes** — drop a `.tsx` file into `.livemark/routes/` to add a fully custom page. See [Custom Routes](https://livemark.dev/customization/custom-routes/).
+
+## Documentation
+
+Full documentation lives at **[livemark.dev](https://livemark.dev)**:
+
+- [Markdown reference](https://livemark.dev/markdown/) — every Markdown / MDX feature with examples
+- [Customization](https://livemark.dev/customization/) — every knob, with copy-pasteable snippets
+- [Changelog](https://livemark.dev/changelog/) — release notes
+- [Contributing](https://livemark.dev/contributing/) — local setup and PR flow
+
+## Resources
+
+- **npm**: [npmjs.com/package/livemark](https://www.npmjs.com/package/livemark)
+- **GitHub**: [github.com/datisthq/livemark](https://github.com/datisthq/livemark)
+- **Issues**: [github.com/datisthq/livemark/issues](https://github.com/datisthq/livemark/issues)
+- **Discussions**: [github.com/datisthq/livemark/discussions](https://github.com/datisthq/livemark/discussions)
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

package/package.json

@@ -1,27 +1,28 @@
 {
   "name": "livemark",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Livemark description",
   "license": "MIT",
   "author": "Evgeny Karev",
   "repository": "https://github.com/datisthq/livemark",
   "bin": {
-    "livemark": "./build/entrypoints/main.js"
+    "livemark": "./target/entrypoints/main.js"
   },
   "files": [
-    "build",
+    "target",
+    "source",
+    "!source/routeTree.gen.ts",
     "skills"
   ],
   "type": "module",
   "sideEffects": false,
-  "imports": {
-    "#*": "./*"
-  },
   "exports": {
-    ".": "./build/index.js",
-    "./components/*": "./build/website/components/*.tsx",
-    "./elements/*": "./build/website/elements/*.tsx",
-    "./styles/*": "./build/website/styles/*.css"
+    ".": "./target/index.js",
+    "./components/*": "./source/components/*.tsx",
+    "./elements/*": "./source/elements/*.tsx",
+    "./hooks/*": "./source/hooks/*.ts",
+    "./styles/*": "./source/styles/*.css",
+    "./utils/*": "./source/utils/*.ts"
   },
   "dependencies": {
     "@base-ui/react": "1.3.0",
@@ -113,11 +114,11 @@
     "pnpm": "^10.0.0"
   },
   "scripts": {
-    "build": "tsgo && rm -rf build/website && cp -r website build",
+    "build": "tsgo",
     "bump": "ncu -u",
-    "clean": "rm -rf pnpm-lock.yaml node_modules build",
-    "docs:build": "node entrypoints/main.ts build",
-    "docs:start": "node entrypoints/main.ts start",
+    "clean": "rm -rf pnpm-lock.yaml node_modules target",
+    "docs:build": "node source/entrypoints/main.ts build",
+    "docs:start": "node source/entrypoints/main.ts start",
     "format": "vp fmt",
     "lint": "vp fmt --check && vp lint",
     "release": "pnpm publish --access public --ignore-scripts --no-git-checks",

package/source/actions/changelog/build.ts

@@ -0,0 +1,245 @@
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { dirname, join, resolve } from "node:path"
+import slugify from "@sindresorhus/slugify"
+import type { Root, RootContent } from "mdast"
+import { toString as mdastToString } from "mdast-util-to-string"
+import remarkParse from "remark-parse"
+import remarkStringify from "remark-stringify"
+import { unified } from "unified"
+import { visit } from "unist-util-visit"
+import type { Config } from "../../models/config.ts"
+import type { ChangelogSection } from "../../models/section.ts"
+import { isGitHubUrl, parseGitHubRepo } from "../../helpers/changelog-source.ts"
+
+interface Release {
+  tag_name: string
+  name?: string | null
+  published_at?: string | null
+  body?: string | null
+  html_url?: string | null
+}
+
+interface CacheMeta {
+  etag: string
+  fetchedAt: string
+}
+
+interface ChangelogEntry {
+  slug: string
+  title: string
+  date?: string
+  body: string
+  sourceUrl?: string
+}
+
+const CACHE_DIR = ".livemark/cache/changelog"
+const META_FILE = ".livemark/cache/changelog.meta.json"
+
+const parser = unified().use(remarkParse)
+const stringifier = unified().use(remarkStringify, {
+  bullet: "-",
+  fences: true,
+  emphasis: "_",
+})
+
+export function cacheIncludeGlob() {
+  return `${CACHE_DIR}/**/*.md`
+}
+
+/** Build the per-version changelog cache files for a changelog section */
+export async function buildChangelog(
+  section: ChangelogSection,
+  config: Config,
+) {
+  const cacheDir = join(config.root, CACHE_DIR)
+  const metaPath = join(config.root, META_FILE)
+
+  const entries = isGitHubUrl(section.source)
+    ? await buildFromGitHub(section.source, metaPath, cacheDir)
+    : await buildFromLocal(section.source, config.root)
+
+  if (entries === undefined) return
+
+  await rm(cacheDir, { recursive: true, force: true })
+  await mkdir(cacheDir, { recursive: true })
+
+  for (const entry of entries) {
+    const markdown = wrapFrontmatter(entry, section)
+    await writeFile(join(cacheDir, `${entry.slug}.md`), markdown, "utf-8")
+  }
+}
+
+async function buildFromLocal(source: string, root: string) {
+  const filePath = resolve(root, source)
+  const body = await readFile(filePath, "utf-8")
+  return splitLocalChangelog(body)
+}
+
+/** Parse CHANGELOG.md into per-version entries using mdast */
+export function splitLocalChangelog(body: string): ChangelogEntry[] {
+  const tree = parser.parse(body) as Root
+  const entries: ChangelogEntry[] = []
+  let current: { heading: string; children: RootContent[] } | undefined
+
+  for (const child of tree.children) {
+    if (child.type === "heading" && child.depth === 2) {
+      if (current) entries.push(finalizeEntry(current))
+      current = { heading: mdastToString(child), children: [] }
+    } else if (current) {
+      current.children.push(child)
+    }
+  }
+  if (current) entries.push(finalizeEntry(current))
+  return entries
+}
+
+function finalizeEntry(input: {
+  heading: string
+  children: RootContent[]
+}): ChangelogEntry {
+  const versionMatch = input.heading.match(/^\[?([^\]\s]+)\]?/)
+  const version = versionMatch?.[1] ?? input.heading
+  const dateMatch = input.heading.match(/\d{4}-\d{2}-\d{2}/)
+  const body = renderEntryBody(input.children)
+  return {
+    slug: slugify(version),
+    title: version,
+    date: dateMatch?.[0],
+    body,
+  }
+}
+
+/** Serialize an entry's mdast children back to markdown */
+function renderEntryBody(children: RootContent[]) {
+  const root: Root = { type: "root", children }
+  return stringifier.stringify(root).trimEnd()
+}
+
+/** Drop the body's leading h1 (typically the conventional-changelog
+ * `# 0.7.2 (2026-04-25)` boilerplate that duplicates the article's title),
+ * shift h2–h6 up by one so subsection headings become h1 / h2 / …, and
+ * escape stray `<` outside code so MDX doesn't mistake them for JSX. */
+function processBody(body: string) {
+  const tree = parser.parse(body) as Root
+  visit(tree, "heading", node => {
+    if (node.depth > 1) node.depth = (node.depth - 1) as 1 | 2 | 3 | 4 | 5
+  })
+  if (tree.children[0]?.type === "heading" && tree.children[0].depth === 1) {
+    tree.children.shift()
+  }
+  return escapeMdxAngles(stringifier.stringify(tree).trimEnd())
+}
+
+/** Escape `<` to `\<` outside fenced code blocks and inline backtick spans
+ * so commit messages with placeholders like `<subdir>` don't get parsed as
+ * JSX by MDX. */
+function escapeMdxAngles(markdown: string) {
+  let inFence = false
+  return markdown
+    .split("\n")
+    .map(line => {
+      if (line.startsWith("```")) {
+        inFence = !inFence
+        return line
+      }
+      if (inFence) return line
+      return line.replace(/`[^`]*`|</g, match =>
+        match === "<" ? "\\<" : match,
+      )
+    })
+    .join("\n")
+}
+
+async function buildFromGitHub(
+  source: string,
+  metaPath: string,
+  cacheDir: string,
+): Promise<ChangelogEntry[] | undefined> {
+  const parsed = parseGitHubRepo(source)
+  if (!parsed) {
+    throw new Error(`Could not parse GitHub repo from source: ${source}`)
+  }
+
+  const url = `https://api.github.com/repos/${parsed.owner}/${parsed.repo}/releases?per_page=100`
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+  }
+
+  const token = process.env.GITHUB_TOKEN
+  if (token) headers.Authorization = `Bearer ${token}`
+
+  const meta = await readMeta(metaPath)
+  const hasCache = await exists(cacheDir)
+  if (meta && hasCache) headers["If-None-Match"] = meta.etag
+
+  const res = await fetch(url, { headers })
+
+  if (res.status === 304) return undefined
+
+  if (!res.ok) {
+    const remaining = res.headers.get("x-ratelimit-remaining")
+    const reset = res.headers.get("x-ratelimit-reset")
+    const msg = `GitHub API ${res.status} ${res.statusText} (rate-limit remaining: ${remaining ?? "?"}, reset: ${reset ?? "?"})`
+    if (hasCache) {
+      console.warn(`${msg} — falling back to cached changelog`)
+      return undefined
+    }
+    throw new Error(msg)
+  }
+
+  const releases = (await res.json()) as Release[]
+  const etag = res.headers.get("etag")
+  if (etag) {
+    await mkdir(dirname(metaPath), { recursive: true })
+    await writeFile(
+      metaPath,
+      JSON.stringify(
+        { etag, fetchedAt: new Date().toISOString() } satisfies CacheMeta,
+        null,
+        2,
+      ),
+      "utf-8",
+    )
+  }
+
+  return releases.map(release => ({
+    slug: slugify(release.tag_name),
+    title: release.tag_name,
+    date: release.published_at ?? undefined,
+    body: (release.body ?? "").trim(),
+    sourceUrl: release.html_url ?? undefined,
+  }))
+}
+
+function wrapFrontmatter(entry: ChangelogEntry, section: ChangelogSection) {
+  const lines = [
+    "---",
+    `title: ${entry.title}`,
+    `path: ${section.prefix}${entry.slug}/`,
+  ]
+  if (entry.date) lines.push(`date: ${entry.date}`)
+  if (entry.sourceUrl) {
+    lines.push(`sourceUrl: ${entry.sourceUrl}`, "sourceAction: view")
+  }
+  lines.push("---", "", `# ${entry.title}`, "", processBody(entry.body))
+  return lines.join("\n")
+}
+
+async function readMeta(metaPath: string): Promise<CacheMeta | undefined> {
+  try {
+    const raw = await readFile(metaPath, "utf-8")
+    return JSON.parse(raw) as CacheMeta
+  } catch {
+    return undefined
+  }
+}
+
+async function exists(path: string) {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/source/actions/changelog/build.unit.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vite-plus/test"
+import { splitLocalChangelog } from "./build.ts"
+
+describe("splitLocalChangelog", () => {
+  it("splits by h2 headings", () => {
+    const input = `# Changelog
+
+## [0.2.0] - 2026-04-15
+
+### Added
+
+- Foo
+
+## [0.1.0] - 2026-04-10
+
+Initial release.
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries).toHaveLength(2)
+    expect(entries[0]?.title).toBe("0.2.0")
+    expect(entries[0]?.date).toBe("2026-04-15")
+    expect(entries[0]?.slug).toBe("0-2-0")
+    expect(entries[1]?.title).toBe("0.1.0")
+    expect(entries[1]?.date).toBe("2026-04-10")
+  })
+
+  it("preserves h3 heading structure in body", () => {
+    const input = `## 1.0.0
+
+### Added
+
+- Thing one
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries[0]?.body).toContain("### Added")
+    expect(entries[0]?.body).toContain("- Thing one")
+  })
+
+  it("ignores ## inside fenced code blocks", () => {
+    const input = `## 1.0.0
+
+Some prose.
+
+\`\`\`md
+## Not a real version heading
+\`\`\`
+
+## 0.9.0
+
+Older.
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries).toHaveLength(2)
+    expect(entries[0]?.title).toBe("1.0.0")
+    expect(entries[0]?.body).toContain("Not a real version heading")
+    expect(entries[1]?.title).toBe("0.9.0")
+  })
+
+  it("handles bare version headings without brackets or date", () => {
+    const input = `## v1.2.3
+
+Release notes.
+`
+    const entries = splitLocalChangelog(input)
+    expect(entries[0]?.title).toBe("v1.2.3")
+    expect(entries[0]?.slug).toBe("v1-2-3")
+    expect(entries[0]?.date).toBeUndefined()
+  })
+})

package/source/actions/config/define.ts

@@ -0,0 +1,11 @@
+import type { z } from "zod"
+import { UserConfig } from "../../models/config.ts"
+
+/**
+ * Validate and fill defaults for a partial config object.
+ */
+export function defineConfig(
+  input: z.input<typeof UserConfig>,
+): z.output<typeof UserConfig> {
+  return UserConfig.parse(input)
+}

package/source/actions/config/define.unit.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vite-plus/test"
+import { defineConfig } from "./define.ts"
+
+describe("defineConfig", () => {
+  it("should accept include as a string", () => {
+    const config = defineConfig({ include: "articles/**/*.mdx" })
+    expect(config.include).toBe("articles/**/*.mdx")
+  })
+
+  it("should accept include as an array", () => {
+    const config = defineConfig({
+      include: ["articles/**/*.mdx", "guides/**/*.mdx"],
+    })
+    expect(config.include).toEqual(["articles/**/*.mdx", "guides/**/*.mdx"])
+  })
+
+  it("should accept optional exclude", () => {
+    const config = defineConfig({
+      include: "**/*.mdx",
+      exclude: "drafts/**",
+    })
+    expect(config.exclude).toBe("drafts/**")
+  })
+
+  it("should allow omitting exclude", () => {
+    const config = defineConfig({ include: "**/*.mdx" })
+    expect(config.exclude).toBeUndefined()
+  })
+
+  it("should reject missing include", () => {
+    expect(() => defineConfig({} as any)).toThrow()
+  })
+})

package/source/actions/config/load.ts

@@ -0,0 +1,22 @@
+import { dirname, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { z } from "zod"
+import type { Config } from "../../models/config.ts"
+import { UserConfig } from "../../models/config.ts"
+import { defineConfig } from "./define.ts"
+
+/**
+ * Load and validate a config file, checking --config/-c CLI arg, then cwd.
+ */
+export async function loadConfig(path?: string): Promise<Config> {
+  const configIndex = process.argv.findIndex(
+    a => a === "-c" || a === "--config",
+  )
+  const cliPath = configIndex !== -1 ? process.argv[configIndex + 1] : undefined
+  const resolved = resolve(path ?? cliPath ?? "livemark.config.ts")
+  // Cache-bust the ESM import so dev-server restart reloads edits on disk.
+  const url = `${pathToFileURL(resolved).href}?t=${Date.now()}`
+  const module: Record<string, unknown> = await import(url)
+  const input = defineConfig(module.default as z.input<typeof UserConfig>)
+  return { ...input, root: dirname(resolved), configPath: resolved }
+}

package/source/actions/config/load.unit.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { loadConfig } from "./load.ts"
+
+describe("loadConfig", () => {
+  it("should throw when no config file exists", async () => {
+    await expect(loadConfig("/nonexistent/config.ts")).rejects.toThrow()
+  })
+
+  it("should load config from explicit path", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const configPath = join(tmpDir, "livemark.config.ts")
+      fs.writeFileSync(
+        configPath,
+        'export default { include: "articles/**/*.mdx" }\n',
+      )
+      const config = await loadConfig(configPath)
+      expect(config.include).toBe("articles/**/*.mdx")
+      expect(config.root).toBe(tmpDir)
+    }))
+
+  it("should validate loaded config", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const configPath = join(tmpDir, "livemark.config.ts")
+      fs.writeFileSync(configPath, "export default {}\n")
+      await expect(loadConfig(configPath)).rejects.toThrow()
+    }))
+})

package/source/commands/build.ts

@@ -0,0 +1,21 @@
+import { join } from "node:path"
+import { Command } from "commander"
+import { createBuilder } from "vite"
+
+const configFile = join(
+  import.meta.dirname,
+  "..",
+  "..",
+  "source",
+  "vite.config.ts",
+)
+
+/**
+ * Build the site for production.
+ */
+export const build = new Command("build")
+  .description("Build the site for production")
+  .action(async () => {
+    const builder = await createBuilder({ configFile })
+    await builder.buildApp()
+  })