livemark 0.24.1 → 0.26.0

package/build/settings.js

@@ -13,6 +13,7 @@ export const ESCAPABLE_FILES = [
     "client.tsx",
     "server.ts",
     "router.tsx",
+    "head.ts",
 ];
 /** Glob patterns auto-excluded from content scanning when the consumer's
  *  project doesn't ship a `.gitignore` to declare its own exclusions. */
@@ -22,4 +23,4 @@ export const DEFAULT_EXCLUDES = [
     "**/build/**",
     "**/dist/**",
 ];
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0dGluZ3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zb3VyY2Uvc2V0dGluZ3MudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7O2dCQUVnQjtBQUNoQixNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBc0I7SUFDbEQsWUFBWTtJQUNaLFVBQVU7SUFDVixRQUFRO0lBQ1IsUUFBUTtJQUNSLFFBQVE7Q0FDVCxDQUFBO0FBRUQsNkVBQTZFO0FBQzdFLE1BQU0sQ0FBQyxNQUFNLGVBQWUsR0FBc0I7SUFDaEQsWUFBWTtJQUNaLFdBQVc7SUFDWCxZQUFZO0NBQ2IsQ0FBQTtBQUVEO3lFQUN5RTtBQUN6RSxNQUFNLENBQUMsTUFBTSxnQkFBZ0IsR0FBc0I7SUFDakQsb0JBQW9CO0lBQ3BCLFlBQVk7SUFDWixhQUFhO0lBQ2IsWUFBWTtDQUNiLENBQUEiLCJzb3VyY2VzQ29udGVudCI6WyIvKiogU3ViZGlycyBvZiBzb3VyY2UvIHdoZXJlIGNvbnN1bWVyIGZpbGVzIGluIGAubGl2ZW1hcmsvPGZvbGRlcj4vYCBhcmVcbiAqICBtZXJnZWQgcGVyLWZpbGUgaW50byB0aGUgcnVudGltZSBtb3VudCwgd2l0aCBgLmxpdmVtYXJrYCB3aW5uaW5nIG9uXG4gKiAgY29uZmxpY3QuICovXG5leHBvcnQgY29uc3QgRVNDQVBBQkxFX0ZPTERFUlM6IHJlYWRvbmx5IHN0cmluZ1tdID0gW1xuICBcImNvbXBvbmVudHNcIixcbiAgXCJlbGVtZW50c1wiLFxuICBcInN0eWxlc1wiLFxuICBcInJvdXRlc1wiLFxuICBcInB1YmxpY1wiLFxuXVxuXG4vKiogVG9wLWxldmVsIHNvdXJjZSBmaWxlcyB0aGF0IGAubGl2ZW1hcmsvPGZpbGU+YCBjYW4gcmVwbGFjZSBhdG9taWNhbGx5LiAqL1xuZXhwb3J0IGNvbnN0IEVTQ0FQQUJMRV9GSUxFUzogcmVhZG9ubHkgc3RyaW5nW10gPSBbXG4gIFwiY2xpZW50LnRzeFwiLFxuICBcInNlcnZlci50c1wiLFxuICBcInJvdXRlci50c3hcIixcbl1cblxuLyoqIEdsb2IgcGF0dGVybnMgYXV0by1leGNsdWRlZCBmcm9tIGNvbnRlbnQgc2Nhbm5pbmcgd2hlbiB0aGUgY29uc3VtZXInc1xuICogIHByb2plY3QgZG9lc24ndCBzaGlwIGEgYC5naXRpZ25vcmVgIHRvIGRlY2xhcmUgaXRzIG93biBleGNsdXNpb25zLiAqL1xuZXhwb3J0IGNvbnN0IERFRkFVTFRfRVhDTFVERVM6IHJlYWRvbmx5IHN0cmluZ1tdID0gW1xuICBcIioqL25vZGVfbW9kdWxlcy8qKlwiLFxuICBcIioqLy5naXQvKipcIixcbiAgXCIqKi9idWlsZC8qKlwiLFxuICBcIioqL2Rpc3QvKipcIixcbl1cbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0dGluZ3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zb3VyY2Uvc2V0dGluZ3MudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7O2dCQUVnQjtBQUNoQixNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBc0I7SUFDbEQsWUFBWTtJQUNaLFVBQVU7SUFDVixRQUFRO0lBQ1IsUUFBUTtJQUNSLFFBQVE7Q0FDVCxDQUFBO0FBRUQsNkVBQTZFO0FBQzdFLE1BQU0sQ0FBQyxNQUFNLGVBQWUsR0FBc0I7SUFDaEQsWUFBWTtJQUNaLFdBQVc7SUFDWCxZQUFZO0lBQ1osU0FBUztDQUNWLENBQUE7QUFFRDt5RUFDeUU7QUFDekUsTUFBTSxDQUFDLE1BQU0sZ0JBQWdCLEdBQXNCO0lBQ2pELG9CQUFvQjtJQUNwQixZQUFZO0lBQ1osYUFBYTtJQUNiLFlBQVk7Q0FDYixDQUFBIiwic291cmNlc0NvbnRlbnQiOlsiLyoqIFN1YmRpcnMgb2Ygc291cmNlLyB3aGVyZSBjb25zdW1lciBmaWxlcyBpbiBgLmxpdmVtYXJrLzxmb2xkZXI+L2AgYXJlXG4gKiAgbWVyZ2VkIHBlci1maWxlIGludG8gdGhlIHJ1bnRpbWUgbW91bnQsIHdpdGggYC5saXZlbWFya2Agd2lubmluZyBvblxuICogIGNvbmZsaWN0LiAqL1xuZXhwb3J0IGNvbnN0IEVTQ0FQQUJMRV9GT0xERVJTOiByZWFkb25seSBzdHJpbmdbXSA9IFtcbiAgXCJjb21wb25lbnRzXCIsXG4gIFwiZWxlbWVudHNcIixcbiAgXCJzdHlsZXNcIixcbiAgXCJyb3V0ZXNcIixcbiAgXCJwdWJsaWNcIixcbl1cblxuLyoqIFRvcC1sZXZlbCBzb3VyY2UgZmlsZXMgdGhhdCBgLmxpdmVtYXJrLzxmaWxlPmAgY2FuIHJlcGxhY2UgYXRvbWljYWxseS4gKi9cbmV4cG9ydCBjb25zdCBFU0NBUEFCTEVfRklMRVM6IHJlYWRvbmx5IHN0cmluZ1tdID0gW1xuICBcImNsaWVudC50c3hcIixcbiAgXCJzZXJ2ZXIudHNcIixcbiAgXCJyb3V0ZXIudHN4XCIsXG4gIFwiaGVhZC50c1wiLFxuXVxuXG4vKiogR2xvYiBwYXR0ZXJucyBhdXRvLWV4Y2x1ZGVkIGZyb20gY29udGVudCBzY2FubmluZyB3aGVuIHRoZSBjb25zdW1lcidzXG4gKiAgcHJvamVjdCBkb2Vzbid0IHNoaXAgYSBgLmdpdGlnbm9yZWAgdG8gZGVjbGFyZSBpdHMgb3duIGV4Y2x1c2lvbnMuICovXG5leHBvcnQgY29uc3QgREVGQVVMVF9FWENMVURFUzogcmVhZG9ubHkgc3RyaW5nW10gPSBbXG4gIFwiKiovbm9kZV9tb2R1bGVzLyoqXCIsXG4gIFwiKiovLmdpdC8qKlwiLFxuICBcIioqL2J1aWxkLyoqXCIsXG4gIFwiKiovZGlzdC8qKlwiLFxuXVxuIl19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livemark",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Livemark description",
   "license": "MIT",
   "author": "Evgeny Karev",
@@ -14,7 +14,7 @@
   "files": [
     "build",
     "source",
-    ".agents/skills"
+    "skills"
   ],
   "type": "module",
   "sideEffects": false,
@@ -26,86 +26,87 @@
     "./styles/*": "./source/styles/*.css"
   },
   "dependencies": {
-    "@base-ui/react": "1.3.0",
-    "@content-collections/core": "0.14.3",
+    "@base-ui/react": "1.9.0",
+    "@clack/prompts": "1.8.1",
+    "@content-collections/core": "0.15.3",
     "@content-collections/mdx": "0.2.2",
-    "@content-collections/vite": "0.3.0",
+    "@content-collections/vite": "0.3.1",
     "@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.3.0",
-    "@tanstack/devtools-vite": "0.7.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",
+    "@shikijs/rehype": "4.5.0",
+    "@shikijs/twoslash": "^4.5.0",
+    "@sindresorhus/slugify": "^3.0.1",
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "4.3.3",
+    "@tanstack/devtools-vite": "0.8.5",
+    "@tanstack/react-devtools": "0.10.13",
+    "@tanstack/react-hotkeys": "^0.13.0",
+    "@tanstack/react-query": "5.104.2",
+    "@tanstack/react-query-devtools": "5.104.2",
+    "@tanstack/react-router": "1.170.42",
+    "@tanstack/react-router-devtools": "1.167.2",
+    "@tanstack/react-router-ssr-query": "1.167.3",
+    "@tanstack/react-start": "1.168.61",
+    "@tanstack/virtual-file-routes": "^1.162.0",
     "@types/mdast": "^4.0.4",
-    "@types/react": "19.2.14",
-    "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "6.0.1",
-    "chokidar": "^5.0.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
     "class-variance-authority": "0.7.1",
     "cmdk": "1.1.1",
-    "cn": "0.2.4",
-    "commander": "14.0.3",
+    "cn": "0.4.0",
+    "commander": "15.0.0",
     "embla-carousel-react": "8.6.0",
-    "es-toolkit": "1.44.0",
+    "es-toolkit": "1.52.0",
     "github-slugger": "^2.0.0",
-    "input-otp": "1.4.2",
-    "katex": "0.18.9",
+    "input-otp": "1.5.0",
+    "katex": "0.19.0",
     "lucide-react": "0.577.0",
-    "mdast-util-directive": "^3.1.0",
+    "mdast-util-directive": "^3.1.1",
     "mdast-util-to-string": "^4.0.0",
-    "mermaid": "^11.14.0",
-    "npm-to-yarn": "^3.0.1",
+    "mermaid": "^12.1.0",
+    "npm-to-yarn": "^3.2.0",
     "picocolors": "1.1.1",
-    "react-day-picker": "9.14.0",
-    "react-medium-image-zoom": "^5.4.2",
-    "react-resizable-panels": "4.9.0",
-    "recharts": "3.8.1",
+    "react-day-picker": "10.0.2",
+    "react-medium-image-zoom": "^5.4.9",
+    "react-resizable-panels": "4.14.4",
+    "recharts": "3.10.1",
     "rehype-katex": "7.0.1",
     "rehype-sanitize": "6.0.0",
     "rehype-slug": "^6.0.0",
-    "remark-definition-list": "^2.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-definition-list": "^2.0.1",
     "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-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
-    "shadcn": "3.7.0",
-    "shiki": "4.0.2",
-    "sonner": "2.0.7",
-    "tailwindcss": "4.2.2",
+    "shadcn": "4.21.4",
+    "shiki": "4.5.0",
+    "sonner": "2.0.8",
+    "tailwindcss": "4.3.3",
     "tw-animate-css": "1.4.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "vaul": "1.1.2",
-    "vite": "8.3.1",
+    "vite": "8.3.4",
     "vite-plugin-svgr": "5.2.0",
-    "zod": "4.3.6"
+    "zod": "4.6.6"
   },
   "devDependencies": {
-    "@plausible-analytics/tracker": "^0.4.4",
-    "@types/node": "24.2.0",
-    "@typescript/native-preview": "7.0.0-dev.20260316.1",
-    "@vitest/coverage-v8": "5.0.1",
-    "lefthook": "2.1.1",
+    "@plausible-analytics/tracker": "^0.4.6",
+    "@types/node": "24.19.2",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitest/coverage-v8": "5.0.3",
+    "lefthook": "2.2.1",
     "livemark": "link:.",
-    "npm-check-updates": "23.1.0",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
+    "npm-check-updates": "23.1.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "tempy": "3.2.0",
-    "vite-plus": "1.0.0",
-    "vitest": "5.0.1",
-    "wrangler": "4.85.0"
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3",
+    "wrangler": "4.149.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -117,18 +118,19 @@
   },
   "scripts": {
     "build": "tsgo --project tsconfig.build.json",
-    "deps": "ncu -u --cooldown 7d",
-    "docs:build": "node source/entrypoints/main.ts build",
-    "docs:start": "node source/entrypoints/main.ts start",
+    "build:docs": "node source/entrypoints/main.ts build",
+    "check": "pnpm check:lint && pnpm check:types",
+    "check:lint": "vp fmt --check && vp lint",
+    "check:types": "tsgo --noEmit",
     "format": "vp fmt --no-error-on-unmatched-pattern",
-    "leaks": "gitleaks git --config=.gitleaks.toml --verbose --redact",
-    "lint": "vp fmt --check && vp lint",
     "release": "pnpm publish --access public --ignore-scripts --no-git-checks",
-    "scan": "pnpm leaks && pnpm vulns",
-    "start": "node source/entrypoints/main.ts",
-    "test": "pnpm lint && pnpm type && pnpm unit",
-    "type": "tsgo --noEmit",
-    "unit": "vp test",
-    "vulns": "semgrep --config=p/typescript --config=p/nodejs --config=p/owasp-top-ten --config=p/secrets --exclude=\"**/fixtures/**\" --metrics=off"
+    "scan": "pnpm scan:leaks && pnpm scan:vulns",
+    "scan:leaks": "gitleaks git --config=.gitleaks.toml --verbose --redact",
+    "scan:vulns": "semgrep --config=p/typescript --config=p/nodejs --config=p/owasp-top-ten --config=p/secrets --exclude=\"**/fixtures/**\" --metrics=off",
+    "squash": "node .scripts/squash-branch.ts",
+    "start": "node source/entrypoints/main.ts start",
+    "test": "pnpm check && pnpm test:unit",
+    "test:unit": "vp test",
+    "update:deps": "ncu -u --cooldown 7d"
   }
 }

package/{.agents/skills → skills}/livemark-authoring/SKILL.md

@@ -36,7 +36,7 @@ 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
+image: ./cover.png # og:image (needs `site`); 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>/
@@ -87,7 +87,7 @@ description: What's new in 0.3, in 400 words.
 
 After authoring, run:
 
-- `pnpm docs:build` — confirms the file prerenders without error.
+- `npx livemark 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

package/{.agents/skills → skills}/livemark-configuration/SKILL.md

@@ -11,7 +11,7 @@ Guidance for editing `livemark.config.ts` at the project root.
 
 Invoke when the user asks to:
 
-- Set the site title, description, canonical URL, logo, favicon.
+- Set the site title, description, canonical URL, logo, favicon, announcement banner.
 - Change which files are included or excluded.
 - Switch code-block syntax highlighting themes.
 - Add, reorder, or retype a section (docs/blog/changelog).
@@ -34,6 +34,13 @@ export default defineConfig({
   description: "Short blurb.", // <meta description>, og:description
   logo: "/logo.svg", // header mark; also default favicon
   favicon: "/favicon.ico", // browser tab icon
+  banner: "v2 is out · [Notes](/blog/v2/)", // inline Markdown strip above the header; raw HTML dropped
+  head: {
+    // extra <head> tags after the defaults; a meta sharing name/property replaces one
+    meta: [{ name: "twitter:site", content: "@me" }],
+    links: [{ rel: "me", href: "https://mastodon.social/@me" }],
+    scripts: [{ src: "https://example.com/analytics.js", defer: "" }],
+  },
 
   // Optional: content selection
   exclude: "docs/drafts/**", // string | string[]
@@ -71,7 +78,7 @@ export default defineConfig({
 - **Blog** (`type: "blog"`): auto-generated index at `prefix`, sorts by `date`, exposes `/prefix/tags/<tag>/` pages.
 - **Changelog** (`type: "changelog"`): reads `source` file; with `version: true`, splits on semver headings into per-version articles. Several changelog sections may coexist as long as their prefixes differ — each is cached in its own `cache/changelog/<slug-of-prefix>-<hash-of-prefix>/` directory (the hash keeps prefixes that slugify alike, like `/python/changelog/` and `/python-changelog/`, apart), so a version shared by two changelogs never collides. The `(version)` suffix only renders for `position: "header"` sections.
 
-Shared fields on every section: `title`, `prefix` (keep trailing-slashed), `type`, `icon` (lucide), `position` (`"header"` default, `"sidebar"` also available).
+Shared fields on every section: `title`, `prefix` (keep trailing-slashed), `type`, `icon` (lucide), `position` (`"header"` default, `"sidebar"` also available). Header sections and links never overflow: past the bar's width Search turns icon-only, then the rest fold into a "More" menu.
 
 Article-to-section matching is longest-prefix-wins on the article's URL `path`.
 
@@ -102,12 +109,12 @@ Any [Shiki theme](https://shiki.style/themes) name works. Defaults keep the catp
 
 ## Autoreload
 
-The dev server watches `livemark.config.ts` and restarts on edit. No need to kill `pnpm docs:start` after tweaking the config.
+The dev server watches `livemark.config.ts` and restarts on edit. No need to kill `npx livemark start` after tweaking the config.
 
 ## Verification
 
-- `pnpm type` — catches schema mismatches.
-- `pnpm docs:build` — prerenders with the new config; the output listing shows whether section routes resolved.
+- The project's type check (e.g. `npx tsc --noEmit`) — catches schema mismatches.
+- `npx livemark build` — prerenders with the new config; the output listing shows whether section routes resolved.
 
 ## References
 

package/skills/livemark-customization/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: livemark-customization
+description: Use when overriding Livemark's built-in UI or adding custom routes — shadow defaults with same-named files under .livemark/{components,elements,styles}, add .livemark/routes/*.tsx pages, or copy defaults with `livemark escape`.
+---
+
+# Livemark Customization
+
+Guidance for customizing the UI layer of a Livemark project beyond what `livemark.config.ts` exposes.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Change a built-in component's layout or markup (Footer, Sidebar, Banner, …).
+- Restyle a shared primitive (buttons, inputs, cards, sheet, …).
+- Rebrand via CSS tokens (colors, radii, typography).
+- Add a brand-new page that isn't a Markdown article (landing hero, pricing page, about page).
+- Replace Livemark's default landing page with a custom React component.
+- Serve a custom `favicon.svg`, `robots.txt`, `og-image.png`, or other static asset.
+
+## Three overlapping mechanisms
+
+| Goal                              | Mechanism                                             |
+| --------------------------------- | ----------------------------------------------------- |
+| Replace a default component/style | Drop a file at `.livemark/components/<Name>.tsx` etc. |
+| Add a new page at an exact URL    | Create `.livemark/routes/<path>.tsx`                  |
+| Serve a static asset at `/<path>` | Put the file in `.livemark/public/<path>`             |
+| Rewrite site-wide `<head>` tags   | `.livemark/head.ts` exporting `customizeHead(head)`   |
+
+None require config changes. The Vite plugin (`source/plugins/vite-livemark.ts`) watches `.livemark/**` and hot-reloads.
+
+## Discovering what's overridable
+
+Run the `escape` command with `--list` to print every overridable file:
+
+```bash
+livemark escape --list
+```
+
+Output is a flat `<subdir>/<file>` list across `components/`, `elements/`, and `styles/`. Without arguments in a terminal the command opens an interactive picker instead — agents should pass `--list` or explicit paths. With paths, it copies each default into `.livemark/`:
+
+```bash
+livemark escape components/Footer.tsx   # → .livemark/components/Footer.tsx
+livemark escape elements/button.tsx styles/general.css   # several at once
+```
+
+The command refuses to overwrite an existing override (and exits 1 after copying the rest). Delete the override first if you want a fresh start.
+
+## Typical workflow: override a component
+
+1. `livemark escape components/Footer.tsx` — copy the default.
+2. Edit `.livemark/components/Footer.tsx`. All the site's Footer renders shift to the new file on save.
+3. Inside the override, import other Livemark modules from the `livemark/<subdir>/*` subpath exports:
+   ```tsx
+   import { cn } from "cn"
+   import { Button } from "livemark/elements/button"
+   ```
+
+## Typical workflow: announcement banner
+
+Prefer the `banner` config option — an inline Markdown string, rendered to HTML at build time and exposed as `bannerHtml` from `livemark:virtual`. Escape `components/Banner.tsx` only for icons or custom markup. The strip spans the full page width above both the sidebar and the sticky header — it scrolls away while the sidebar and header pin to the top (the sidebar container is `sticky`, not `fixed`, for this). Let it wrap (`flex-wrap`, `text-balance`, `min-w-0`) rather than `truncate`, so phones neither clip it nor scroll sideways. Style the injected HTML from the wrapper (`[&_a]:underline`): Tailwind never sees classes inside a config string. Search and the theme toggle sit at the right of the header, not in the sidebar. The header's section strip is `components/HeaderNav.tsx`; it tells `Header` when to render `<Search compact />` and folds what still doesn't fit into a "More" menu. Below `lg`, `Search` opens `components/HeaderSearch.tsx` instead of the dialog: a field that covers the whole header bar, with results dropping full-width beneath it — positioned `absolute` against the sticky header, so an override must stay inside `<header>`.
+
+## Sidebar escapes
+
+`Sidebar` picks the body slot (`SidebarArticles`, `SidebarPosts`, `SidebarReleases`) and passes each, plus `SidebarLinks`, the section to show as an optional `section` prop. On mobile inside a section it swaps the Sections list for `SidebarSectionPicker`, which changes that prop without navigating — an escaped body slot must read `props.section` before falling back to the route's section, or the picker stops working.
+
+## Typical workflow: rebrand
+
+1. `livemark escape styles/general.css`.
+2. Edit the `:root` and `.dark` blocks in `.livemark/styles/general.css`:
+   - `--primary` — brand accent (Tailwind-flavoured oklch values work).
+   - `--positive`, `--warning`, `--destructive` — status tones, each with a `-foreground` for text on the fill and a `-tint` / `-tint-foreground` pair for soft surfaces (callouts, diff lines, badge and button variants).
+   - `--radius` — the `rounded-sm`…`rounded-xl` scale only. Element corners are named tokens in `styles/shape.css` (`rounded-control` pills, `rounded-card`/`rounded-row`/`rounded-menu` 1rem, `rounded-panel` 1.5rem); escape that file to change them, and use those names rather than raw `rounded-md` in new elements.
+   - Sidebar / chart tokens if you want deeper tweaks.
+3. Save — the dev server applies immediately.
+
+Whole-site contrast is audited: light mode targets blue-600, dark mode targets blue-500. Keep new token values AA-compliant on both backgrounds (≥4.5:1 for text).
+
+## Typical workflow: add a page
+
+Custom routes use [TanStack Router](https://tanstack.com/router). Minimal example:
+
+```tsx title=".livemark/routes/about.tsx"
+import { createFileRoute } from "@tanstack/react-router"
+import { Layout } from "livemark/components/Layout"
+
+export const Route = createFileRoute("/about")({
+  component: () => (
+    <Layout>
+      <div className="mx-auto max-w-3xl px-6 py-16 prose">
+        <h1>About</h1>
+        <p>Hello.</p>
+      </div>
+    </Layout>
+  ),
+})
+```
+
+A custom route renders **bare**: the root wraps every route in the headless `components/Root.tsx`, and only the Markdown route, 404 and error pages add chrome. Pick it per route:
+
+- `<Layout>` — banner, header, sidebar sheet and back-to-top, as articles get (`withSidebar` adds the article sidebar)
+- `<Banner />` + `<Header />` — a landing page's chrome without the sidebar; on phones `Header` opens `HeaderMenu`, a flat list of the header sections and links
+- nothing — a fully custom page
+
+`Header` never reads sidebar context: `Layout` passes its `SidebarTrigger`s in as the `toggle` and `menu` slots. A `Header` without `toggle` keeps its title block at sidebar width so the nav lines up with article pages.
+
+Filename maps to URL path: `.livemark/routes/pricing.tsx` → `/pricing/`. Nested paths work via nested folders.
+
+An `index.tsx` in `.livemark/routes/` **replaces** Livemark's default landing at `/`.
+
+Custom routes win over the Markdown catch-all at exact URLs. Don't create a route that collides with an article URL unless you intend to hide the article.
+
+## Rules of thumb
+
+1. **Don't fork the repo** for routine customization. Use `.livemark/` first — it reliably survives Livemark upgrades.
+2. **Same filename, same path under `.livemark/`.** The override plugin is case-sensitive and mirrors the subdirectory structure exactly.
+3. **Override files are full replacements**, not diffs. Copy the default first (via `escape`), then edit.
+4. **Import Livemark internals via `livemark/*`**, not via relative paths — the plugin resolves those to the project's copy, so chained overrides (e.g., your Layout using your Header) compose correctly.
+5. **Static files belong in `.livemark/public/`**, which Vite exposes at the site root.
+6. **Never edit `.livemark/.target/`** — it is the generated mount Vite runs (Livemark's source with your overrides copied in), rebuilt on every run, so stack traces point there but edits are lost. Gitignore it alongside `.livemark/build/`.
+7. **Keyboard shortcuts live in the component they drive** — bare keys through `@tanstack/react-hotkeys`, ignored while typing: `L` sidebar (`Sidebar`), `S` search (`Search`), `T` theme (`Theme`), `J`/`K` scroll (`Root`), `B` back to top (`BackToTop`). Overriding one of these drops its key unless the copy keeps the `useHotkey` call; register a key in a component that mounts once, or one press fires twice.
+8. **Search highlights live in `Article`** — picking a result opens the page with `?highlight=<query>`, and `Article` passes it to `useSearchHighlight` with a ref on its `.prose` wrapper. An overridden `components/Article.tsx` must keep that call and ref, or matches stop being marked. Theme the mark through the `--highlight` and `--highlight-foreground` tokens; code blocks are never marked.
+
+## Head tags
+
+Add tags with the config `head` field (`livemark-configuration`); escape `head.ts` only to drop or rewrite defaults. `customizeHead` receives the finished `RootHead` (`meta`, `links`, `scripts`, typed from `livemark`) and returns it — mutate or filter, never rebuild, or later Livemark defaults are lost. Per-page `title`, `description`, `og:*` and canonical come from the article route and win over root meta with the same `name`/`property`.
+
+## What's NOT overridable
+
+- `actions/`, `commands/`, `program.ts` — server/CLI code. Fork upstream if you need to change these.
+- `livemark.config.ts` schema — fixed.
+- Content-collections transform pipeline. Customize markdown via remark/rehype plugins in a fork (or PR upstream).
+
+## Verification
+
+- The project's type check (e.g. `npx tsc --noEmit`) — confirms overrides typecheck.
+- `npx livemark build` — smoke-test the override lands in the bundle.
+- Browser: load an article page with the dev server; custom Footer/Sidebar/etc. should render without a full reload.
+
+## References
+
+- Narrative docs: `docs/customization/file-overrides.md`, `docs/customization/custom-routes.md`.
+- Plugin implementation: `source/plugins/vite-livemark.ts`.
+- Escape command: `commands/escape.ts`; list and copy logic in `actions/escape/`.
+- Subpath exports: `package.json` `exports` block.

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

@@ -31,4 +31,13 @@ describe("defineConfig", () => {
     const config = defineConfig({})
     expect(config.include).toBe("**/*.md")
   })
+
+  it("should accept an inline Markdown banner", () => {
+    const config = defineConfig({ banner: "Hi · [x](/y/)" })
+    expect(config.banner).toBe("Hi · [x](/y/)")
+  })
+
+  it("should leave banner unset by default", () => {
+    expect(defineConfig({}).banner).toBeUndefined()
+  })
 })

package/source/actions/escape/copy.ts

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { ESCAPABLE_FILES, ESCAPABLE_FOLDERS } from "../../settings.ts"
+
+/**
+ * Copy a livemark default into `<root>/.livemark/<path>`.
+ *
+ * Throws when the path is not escapable, is not a livemark file, or the
+ * destination already exists. Returns the destination path.
+ */
+export function copyEscape(props: { root: string; sourceRoot: string; path: string }) {
+  const isTopLevelFile = !props.path.includes("/") && ESCAPABLE_FILES.includes(props.path)
+  const [first] = props.path.split("/")
+  const isFolderPath =
+    !!first && ESCAPABLE_FOLDERS.includes(first) && !props.path.includes("..")
+  if (!isTopLevelFile && !isFolderPath) {
+    throw new Error(
+      `'${props.path}' is not escapable (folders: ${ESCAPABLE_FOLDERS.join(", ")}; files: ${ESCAPABLE_FILES.join(", ")})`,
+    )
+  }
+
+  const src = join(props.sourceRoot, props.path)
+  if (!existsSync(src) || !statSync(src).isFile()) {
+    throw new Error(`'${props.path}' is not a livemark file`)
+  }
+
+  const dest = join(props.root, ".livemark", props.path)
+  if (existsSync(dest)) {
+    throw new Error(`.livemark/${props.path} already exists`)
+  }
+
+  mkdirSync(dirname(dest), { recursive: true })
+  writeFileSync(dest, readFileSync(src))
+  return dest
+}

package/source/actions/escape/copy.unit.ts

@@ -0,0 +1,51 @@
+import fs from "node:fs"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { copyEscape } from "./copy.ts"
+
+describe("copyEscape", () => {
+  it("should copy a default into .livemark/", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const sourceRoot = createSource(tmpDir)
+      const dest = copyEscape({ root: tmpDir, sourceRoot, path: "components/Footer.tsx" })
+      expect(dest).toBe(join(tmpDir, ".livemark", "components", "Footer.tsx"))
+      expect(fs.readFileSync(dest, "utf8")).toBe("default\n")
+    }))
+
+  it("should refuse to overwrite an existing override", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const sourceRoot = createSource(tmpDir)
+      copyEscape({ root: tmpDir, sourceRoot, path: "client.tsx" })
+      expect(() => copyEscape({ root: tmpDir, sourceRoot, path: "client.tsx" })).toThrow(
+        /already exists/,
+      )
+    }))
+
+  it("should reject paths outside the escape contract", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const sourceRoot = createSource(tmpDir)
+      for (const path of ["index.ts", "components/../index.ts", "helpers/toc.ts"]) {
+        expect(() => copyEscape({ root: tmpDir, sourceRoot, path })).toThrow(
+          /not escapable/,
+        )
+      }
+    }))
+
+  it("should reject an escapable path with no livemark file", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const sourceRoot = createSource(tmpDir)
+      expect(() =>
+        copyEscape({ root: tmpDir, sourceRoot, path: "components/Missing.tsx" }),
+      ).toThrow(/not a livemark file/)
+    }))
+})
+
+function createSource(tmpDir: string) {
+  const sourceRoot = join(tmpDir, "source")
+  fs.mkdirSync(join(sourceRoot, "components"), { recursive: true })
+  fs.writeFileSync(join(sourceRoot, "components", "Footer.tsx"), "default\n")
+  fs.writeFileSync(join(sourceRoot, "client.tsx"), "default\n")
+  fs.writeFileSync(join(sourceRoot, "index.ts"), "default\n")
+  return sourceRoot
+}

package/source/actions/escape/list.ts

@@ -0,0 +1,30 @@
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { ESCAPABLE_FILES, ESCAPABLE_FOLDERS } from "../../settings.ts"
+
+/** An escapable livemark file and whether the project already shadows it. */
+export interface Escape {
+  path: string
+  escaped: boolean
+}
+
+/**
+ * List every file a project can shadow under `.livemark/`, sorted by path.
+ */
+export function listEscapes(props: { root: string; sourceRoot: string }) {
+  const paths: string[] = []
+  for (const folder of ESCAPABLE_FOLDERS) {
+    const dir = join(props.sourceRoot, folder)
+    if (!existsSync(dir)) continue
+    for (const entry of readdirSync(dir)) {
+      if (statSync(join(dir, entry)).isFile()) paths.push(`${folder}/${entry}`)
+    }
+  }
+  for (const file of ESCAPABLE_FILES) {
+    if (existsSync(join(props.sourceRoot, file))) paths.push(file)
+  }
+  return paths.sort().map((path): Escape => ({
+    path,
+    escaped: existsSync(join(props.root, ".livemark", path)),
+  }))
+}

package/source/actions/escape/list.unit.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs"
+import { join } from "node:path"
+import { temporaryDirectoryTask } from "tempy"
+import { describe, expect, it } from "vite-plus/test"
+import { listEscapes } from "./list.ts"
+
+describe("listEscapes", () => {
+  it("should list folder files and top-level files, sorted", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const sourceRoot = join(tmpDir, "source")
+      writeFile(join(sourceRoot, "components", "Footer.tsx"))
+      writeFile(join(sourceRoot, "styles", "general.css"))
+      writeFile(join(sourceRoot, "client.tsx"))
+      writeFile(join(sourceRoot, "index.ts"))
+      fs.mkdirSync(join(sourceRoot, "elements", "nested"), { recursive: true })
+
+      const escapes = listEscapes({ root: tmpDir, sourceRoot })
+      expect(escapes.map(escape => escape.path)).toEqual([
+        "client.tsx",
+        "components/Footer.tsx",
+        "styles/general.css",
+      ])
+    }))
+
+  it("should mark files the project already shadows", () =>
+    temporaryDirectoryTask(async tmpDir => {
+      const sourceRoot = join(tmpDir, "source")
+      writeFile(join(sourceRoot, "components", "Footer.tsx"))
+      writeFile(join(sourceRoot, "components", "Header.tsx"))
+      writeFile(join(tmpDir, ".livemark", "components", "Footer.tsx"))
+
+      expect(listEscapes({ root: tmpDir, sourceRoot })).toEqual([
+        { path: "components/Footer.tsx", escaped: true },
+        { path: "components/Header.tsx", escaped: false },
+      ])
+    }))
+})
+
+function writeFile(path: string) {
+  fs.mkdirSync(join(path, ".."), { recursive: true })
+  fs.writeFileSync(path, "default\n")
+}