livemark 0.2.0 → 0.7.1

package/build/website/styles/general.css

@@ -0,0 +1,163 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@plugin "@tailwindcss/typography";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(54.6% 0.245 262.881);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(89.4% 0.057 293.283);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.5 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.145 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.145 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.623 0.214 259.815);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.396 0.141 25.723);
+  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --border: oklch(0.269 0 0);
+  --input: oklch(0.269 0 0);
+  --ring: oklch(0.439 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(0.269 0 0);
+  --sidebar-ring: oklch(0.439 0 0);
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+
+  html {
+    scroll-behavior: smooth;
+    scrollbar-color: #ddd transparent;
+    scrollbar-gutter: stable;
+  }
+
+  button:not([disabled]),
+  [role="button"]:not([disabled]) {
+    cursor: pointer;
+  }
+
+  [data-slot="sidebar-content"] {
+    scrollbar-width: thin;
+    scrollbar-color: transparent transparent;
+    transition: scrollbar-color 0.2s;
+  }
+  [data-slot="sidebar-content"]:hover,
+  [data-slot="sidebar-content"]:focus-within {
+    scrollbar-color: color-mix(
+        in oklch,
+        var(--sidebar-foreground) 20%,
+        transparent
+      )
+      transparent;
+  }
+
+  [data-slot="sidebar-content"]::-webkit-scrollbar {
+    width: 8px;
+  }
+  [data-slot="sidebar-content"]::-webkit-scrollbar-thumb {
+    background: transparent;
+    border-radius: 9999px;
+    transition: background 0.2s;
+  }
+  [data-slot="sidebar-content"]:hover::-webkit-scrollbar-thumb,
+  [data-slot="sidebar-content"]:focus-within::-webkit-scrollbar-thumb {
+    background: color-mix(in oklch, var(--sidebar-foreground) 20%, transparent);
+  }
+}

package/build/website/styles/markdown.css

@@ -0,0 +1,214 @@
+@import "katex/dist/katex.min.css";
+@reference "./general.css";
+
+@layer components {
+  .prose :is(h1, h2, h3, h4, h5, h6) {
+    @apply scroll-mt-28 md:scroll-mt-20;
+  }
+
+  .prose :is(h1, h2, h3, h4, h5, h6)[id] {
+    position: relative;
+  }
+
+  .prose :is(h1, h2, h3, h4, h5, h6)[id]::after {
+    content: "";
+    display: inline-block;
+    width: 0.6em;
+    height: 0.6em;
+    margin-left: 0.4em;
+    vertical-align: middle;
+    opacity: 0;
+    transition: opacity 0.15s;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71'/%3E%3Cpath d='M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71'/%3E%3C/svg%3E");
+    background-size: contain;
+    background-repeat: no-repeat;
+  }
+
+  .prose :is(h1, h2, h3, h4, h5, h6)[id]:hover::after {
+    opacity: 0.5;
+  }
+
+  .prose :is(h1, h2, h3, h4, h5, h6)[id] a,
+  .prose :is(h1, h2, h3, h4, h5, h6)[id] a:hover {
+    color: inherit !important;
+    text-decoration: none !important;
+  }
+
+  .prose pre code .line {
+    @apply px-4;
+  }
+
+  .prose pre code .line[data-highlighted] {
+    @apply bg-primary/10;
+  }
+
+  .prose pre code .line[data-diff="add"] {
+    @apply bg-green-500/15;
+  }
+
+  .prose pre code .line[data-diff="remove"] {
+    @apply bg-red-500/15;
+  }
+
+  .prose pre code .line[data-diff="add"]::before {
+    content: "+";
+    @apply text-green-600 absolute left-1;
+  }
+
+  .prose pre code .line[data-diff="remove"]::before {
+    content: "-";
+    @apply text-red-600 absolute left-1;
+  }
+
+  .prose pre code .line[data-line-status="error"] {
+    @apply bg-red-500/15;
+  }
+
+  .prose pre code .line[data-line-status="warning"] {
+    @apply bg-yellow-500/15;
+  }
+
+  .prose pre[data-has-focus] code .line:not([data-focus]) {
+    @apply opacity-30;
+  }
+
+  .prose pre[data-has-focus] code .line[data-focus] {
+    @apply opacity-100;
+  }
+
+  .prose pre code [data-word-highlighted] {
+    @apply bg-primary/20 rounded px-0.5 py-0.5;
+  }
+
+  .prose pre code .line[data-line-number]::before {
+    content: attr(data-line-number);
+    display: inline-block;
+    width: 2rem;
+    margin-right: 1rem;
+    text-align: right;
+    color: var(--color-muted-foreground);
+    opacity: 0.5;
+    user-select: none;
+  }
+
+  .prose pre code .twoslash-popup-container {
+    @apply absolute z-10 translate-y-1 rounded-md border border-border bg-popover px-3 py-1.5 text-xs shadow-md;
+  }
+
+  .prose pre code .twoslash-popup-type {
+    @apply font-mono text-muted-foreground;
+  }
+
+  .prose pre code .twoslash-error-line {
+    @apply bg-red-500/10;
+  }
+
+  .prose pre code .twoslash-tag-line {
+    @apply opacity-50;
+  }
+
+  .prose pre code .twoslash-completion-list {
+    @apply absolute z-10 translate-y-1 rounded-md border border-border bg-popover p-1 text-xs shadow-md;
+  }
+
+  .prose pre code .twoslash-completion-list .twoslash-completion-item {
+    @apply px-2 py-0.5;
+  }
+
+  .prose pre code .twoslash-hover .twoslash-popup-container {
+    @apply hidden;
+  }
+
+  .prose pre code .twoslash-hover:hover .twoslash-popup-container {
+    @apply block;
+  }
+
+  .prose :not(pre) > code {
+    @apply bg-muted/70 border border-border rounded-md px-1.5 py-0.5 text-sm font-mono;
+  }
+
+  .prose :not(pre) > code::before,
+  .prose :not(pre) > code::after {
+    content: none !important;
+  }
+
+  .prose code.shiki-inline {
+    @apply bg-muted/70 border border-border rounded-md px-1.5 py-0.5 text-sm font-mono;
+  }
+
+  .prose code.shiki-inline .line {
+    display: inline;
+  }
+
+  .dark .shiki span {
+    color: var(--shiki-dark) !important;
+  }
+
+  .katex-display {
+    @apply overflow-x-auto overflow-y-hidden;
+  }
+
+  .katex {
+    @apply overflow-x-auto overflow-y-hidden;
+  }
+
+  .prose ul:has(> li > input[type="checkbox"]) {
+    padding-inline-start: 0.5em;
+  }
+
+  .prose ul > li:has(> input[type="checkbox"]) {
+    list-style-type: none;
+    padding-left: 0;
+  }
+
+  .prose [data-footnotes] {
+    @apply mt-8 border-t border-border pt-4 text-sm text-muted-foreground;
+  }
+
+  .prose [data-footnotes] ol {
+    @apply list-decimal pl-6;
+  }
+
+  .prose sup a[data-footnote-ref] {
+    @apply ml-0.5 px-0.5 text-primary text-xs no-underline font-medium;
+  }
+
+  .prose [data-footnotes] a[data-footnote-backref] {
+    @apply text-primary no-underline;
+  }
+
+  .prose dl {
+    @apply my-4;
+  }
+
+  .prose dt {
+    @apply font-semibold mt-4 first:mt-0;
+  }
+
+  .prose dd {
+    @apply ml-6 mt-1 text-muted-foreground;
+  }
+
+  .prose {
+    counter-reset: step;
+  }
+
+  .prose [data-step] {
+    counter-increment: step;
+  }
+
+  .prose [data-step]::before {
+    content: counter(step);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    border-radius: 9999px;
+    background: var(--color-primary);
+    color: white;
+    font-size: 0.75rem;
+    font-weight: 600;
+    margin-right: 0.5rem;
+  }
+}

package/build/website/vite.config.ts

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join, relative } from "node:path"
+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"
+import {
+  physical,
+  rootRoute,
+  route,
+  type VirtualRouteNode,
+} from "@tanstack/virtual-file-routes"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+import svgr from "vite-plugin-svgr"
+import { loadConfig } from "../actions/config/load.ts"
+import { WebsiteConfig } from "../models/config.ts"
+import { livemark, OVERRIDE_SUBDIRS } from "./plugins/vite-livemark.ts"
+
+const config = await loadConfig()
+const websiteDir = import.meta.dirname
+const websiteRelative = relative(config.root, websiteDir)
+const overridesRoot = join(config.root, ".livemark")
+
+// Seed `.livemark/.gitignore` on first run so Vite's build/cache artifacts
+// never get committed by accident.
+const gitignorePath = join(overridesRoot, ".gitignore")
+if (!existsSync(gitignorePath)) {
+  mkdirSync(overridesRoot, { recursive: true })
+  writeFileSync(gitignorePath, "/build\n/cache\n")
+}
+
+const routeChildren: VirtualRouteNode[] = [route("/$", "$.tsx")]
+if (existsSync(join(overridesRoot, "routes"))) {
+  routeChildren.push(physical("../../.livemark/routes"))
+}
+
+export default defineConfig({
+  root: config.root,
+  publicDir: join(config.root, ".livemark", "public"),
+  build: { outDir: ".livemark/build" },
+  define: {
+    "import.meta.env.CONFIG": JSON.stringify(WebsiteConfig.parse(config)),
+  },
+  plugins: [
+    livemark({
+      defaultsRoot: websiteDir,
+      overridesRoot,
+      subdirs: [...OVERRIDE_SUBDIRS],
+      configPath: config.configPath,
+    }),
+    devtools(),
+    tailwind(),
+    contentCollections({
+      configPath: join(websiteRelative, "content-collections.ts"),
+    }),
+    tanstackStart({
+      srcDirectory: websiteRelative,
+      pages: [{ path: "/" }],
+      prerender: { enabled: true, crawlLinks: true },
+      sitemap: config.site
+        ? { enabled: true, host: config.site }
+        : { enabled: false },
+      router: {
+        virtualRouteConfig: rootRoute("__root.tsx", routeChildren),
+      },
+    }),
+    react(),
+    svgr(),
+  ],
+})

package/package.json

@@ -1,21 +1,129 @@
 {
   "name": "livemark",
-  "type": "module",
-  "main": "build/index.js",
-  "version": "0.2.0",
+  "version": "0.7.1",
+  "description": "Livemark description",
   "license": "MIT",
   "author": "Evgeny Karev",
   "repository": "https://github.com/datisthq/livemark",
-  "description": "Livemark implementation in TypeScript.",
-  "keywords": [
-    "markdown",
-    "typescript",
-    "documentation",
-    "quality",
-    "testing",
-    "cli"
+  "bin": {
+    "livemark": "./build/entrypoints/main.js"
+  },
+  "files": [
+    "build",
+    "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"
+  },
+  "dependencies": {
+    "@base-ui/react": "1.3.0",
+    "@content-collections/core": "0.14.3",
+    "@content-collections/mdx": "0.2.2",
+    "@content-collections/vite": "0.3.0",
+    "@orama/orama": "^3.1.18",
+    "@shikijs/rehype": "4.0.2",
+    "@shikijs/twoslash": "^4.0.2",
+    "@sindresorhus/slugify": "^3.0.0",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "4.2.4",
+    "@tanstack/devtools-vite": "0.6.0",
+    "@tanstack/react-devtools": "0.10.0",
+    "@tanstack/react-hotkeys": "^0.9.1",
+    "@tanstack/react-query": "5.91.3",
+    "@tanstack/react-query-devtools": "5.91.3",
+    "@tanstack/react-router": "1.168.1",
+    "@tanstack/react-router-devtools": "1.166.10",
+    "@tanstack/react-router-ssr-query": "1.166.10",
+    "@tanstack/react-start": "1.167.2",
+    "@tanstack/virtual-file-routes": "^1.161.7",
+    "@types/mdast": "^4.0.4",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "6.0.1",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "cmdk": "1.1.1",
+    "commander": "14.0.3",
+    "embla-carousel-react": "8.6.0",
+    "es-toolkit": "1.44.0",
+    "github-slugger": "^2.0.0",
+    "input-otp": "1.4.2",
+    "katex": "^0.16.44",
+    "lucide-react": "0.577.0",
+    "mdast-util-directive": "^3.1.0",
+    "mdast-util-to-string": "^4.0.0",
+    "mermaid": "^11.14.0",
+    "npm-to-yarn": "^3.0.1",
+    "picocolors": "1.1.1",
+    "react": "19.2.4",
+    "react-day-picker": "9.14.0",
+    "react-dom": "19.2.4",
+    "react-medium-image-zoom": "^5.4.2",
+    "react-resizable-panels": "4.9.0",
+    "recharts": "3.8.1",
+    "rehype-katex": "7.0.1",
+    "rehype-sanitize": "6.0.0",
+    "rehype-slug": "^6.0.0",
+    "remark-definition-list": "^2.0.0",
+    "remark-directive": "^4.0.0",
+    "remark-gemoji": "^8.0.0",
+    "remark-gfm": "4.0.1",
+    "remark-math": "6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "shadcn": "3.7.0",
+    "shiki": "4.0.2",
+    "sonner": "2.0.7",
+    "tailwind-merge": "3.5.0",
+    "tailwindcss": "4.2.2",
+    "tw-animate-css": "1.4.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "vaul": "1.1.2",
+    "vite": "8.0.10",
+    "vite-plugin-svgr": "5.2.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@semantic-release/exec": "7.1.0",
+    "@types/node": "24.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260316.1",
+    "@vitest/coverage-v8": "4.1.5",
+    "conventional-changelog-conventionalcommits": "9.1.0",
+    "husky": "9.1.7",
+    "is-ci": "4.1.0",
+    "lefthook": "2.1.1",
+    "npm-check-updates": "18.0.1",
+    "semantic-release": "24.2.9",
+    "tempy": "3.2.0",
+    "vite-plus": "0.1.19",
+    "vitest-polly": "2.1.0",
+    "wrangler": "4.85.0"
+  },
+  "engines": {
+    "node": "^24.0.0",
+    "pnpm": "^10.0.0"
+  },
   "scripts": {
-    "build": "tsc --build"
+    "build": "tsgo && rm -rf build/website && cp -r website build",
+    "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",
+    "format": "vp fmt",
+    "lint": "vp fmt --check && vp lint",
+    "release": "pnpm publish --access public --ignore-scripts --no-git-checks",
+    "setversion": "pnpm version --no-git-tag-version",
+    "unit": "vp test",
+    "test": "pnpm lint && pnpm type && pnpm unit",
+    "type": "tsgo --noEmit"
   }
 }

package/skills/authoring/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: livemark-authoring
+description: Use when adding or editing Markdown articles in a Livemark project — covers file placement under include globs, frontmatter fields, sidebar grouping, URL derivation, images/assets, and the patches mechanism for files that can't carry frontmatter.
+---
+
+# Livemark Authoring
+
+Guidance for writing and maintaining Markdown content in a Livemark project.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Add a new article, page, or docs section.
+- Rename, reorder, hide, or regroup an existing article.
+- Set metadata (title, icon, tags, date, author, OG image).
+- Patch a file (typically `README.md`) that needs Livemark metadata without dirtying its upstream rendering.
+
+## Where articles live
+
+- Livemark collects Markdown files that match the `include` glob(s) in `livemark.config.ts`. The default project layout is `docs/**/*.md`. Respect existing convention in the repo.
+- Files ending in `.md` are supported by default. Drafts/partials can be co-located but excluded via the `exclude` glob (e.g. `docs/**/_*.md`).
+
+## Frontmatter template
+
+Every field is optional. Livemark derives defaults from the file itself.
+
+```yaml
+---
+title: Getting Started # default: first `# ` heading, else filename
+label: Start # short variant used in sidebar/breadcrumbs
+description: A one-line blurb. # used in <meta description> and OG
+icon: rocket # lucide icon name
+order: 1 # sidebar sort; negatives pin to end
+group: Docs # sidebar section label
+path: /getting-started/ # default: slugified filename + leading/trailing slashes
+sidebar: true # false hides from nav but keeps URL reachable
+toc: true # false suppresses right-hand TOC
+image: ./cover.png # OG/social card; relative resolves against the file
+author: Ada Lovelace # or [Ada Lovelace, Grace Hopper]
+date: 2026-04-20 # ISO — drives blog section sort order
+tags: [release, announcement] # blog-section tag pages /prefix/tags/<tag>/
+---
+```
+
+## Rules of thumb
+
+1. **One H1 per file.** Livemark uses the first `# ` for the title when frontmatter `title` is omitted. Don't add a duplicate H1 in the body if the frontmatter already sets `title`.
+2. **Order is piecewise.** Positive numbers sort first ascending, unordered articles come next, negative numbers land at the end (`-1` last, `-2` second-to-last). Leave the middle alone — only set `order` on items you want pinned.
+3. **Grouping.** Contiguous root-level articles with the same `group` string render under a labelled sidebar section. Mixing groups breaks visual grouping.
+4. **URLs.** Don't set `path` unless you need to override the default slug. Livemark derives `path` from the filename plus leading/trailing slashes.
+5. **Images.** Relative paths in `image`, Markdown `![](...)`, and MDX `<img src>` resolve against the article file — keep assets co-located or under `docs/images/`.
+
+## Patching a file you can't touch
+
+When a file already lives on disk (for example `README.md` that GitHub renders) and you don't want to pollute it with frontmatter, inject metadata via `patches` in `livemark.config.ts`:
+
+```ts
+patches: [
+  {
+    file: "README.md",
+    article: { title: "Overview", icon: "sparkles", order: 0 },
+  },
+]
+```
+
+The `file` field is exact-match on the collection-relative path. `content` cannot be patched — zod rejects at config load.
+
+## Blog posts
+
+For a blog section:
+
+```yaml
+---
+title: "Announcing v0.3"
+date: 2026-04-20
+author: Livemark Team
+tags: [release, announcement]
+image: ./images/v0-3.png
+description: What's new in 0.3, in 400 words.
+---
+```
+
+`date` is required for correct chronological sort. `tags` drive the `/<prefix>/tags/<tag>/` pages.
+
+## Verification
+
+After authoring, run:
+
+- `pnpm docs:build` — confirms the file prerenders without error.
+- Grep built HTML (`.livemark/build/client/<path>/index.html`) to confirm title and metadata land as intended.
+
+## References
+
+- Full frontmatter reference: `docs/markdown/frontmatter.md`.
+- Schema source of truth: `website/models/article.ts`.
+- Transform pipeline: `website/content-collections.ts`.