livemark 0.0.0-dev → 0.7.0

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/toc-context.ts

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

package/build/website/helpers/toc.ts

@@ -1,10 +1,5 @@
 import GithubSlugger from "github-slugger"
-
-export interface TocItem {
-  url: string
-  title: string
-  depth: number
-}
+import type { TocItem } from "../models/toc.ts"
 
 const CUSTOM_ID_PATTERN = /\s*\[#([^\]]+)\]\s*$/
 const TOC_HIDDEN_PATTERN = /\s*\[!toc\]\s*$/

package/build/website/models/article.ts

@@ -1,40 +1,55 @@
+import { z } from "zod"
+import { nonEmptyString } from "../helpers/model.ts"
+import type { TocItem } from "./toc.ts"
+
+/** Frontmatter schema for a markdown article. */
+export type Article = z.infer<typeof Article>
+export const Article = z.object({
+  content: z.string(),
+  title: nonEmptyString.optional(),
+  label: nonEmptyString.optional(),
+  description: nonEmptyString.optional(),
+  icon: nonEmptyString.optional(),
+  order: z.number().optional(),
+  path: nonEmptyString.optional(),
+  group: nonEmptyString.optional(),
+  sidebar: z.boolean().default(true),
+  toc: z.boolean().default(true),
+  image: nonEmptyString.optional(),
+  author: z.union([nonEmptyString, z.array(nonEmptyString)]).optional(),
+  date: nonEmptyString.optional(),
+  tags: z.array(nonEmptyString).optional(),
+})
+
+/** Processed article ready for page rendering (result of content-collections transform). */
+export interface ArticleView {
+  path: string
+  content: string
+  file: string
+  mdx: string
+  tocItems: TocItem[]
+  toc?: boolean
+  lastUpdated?: string
+  sidebar?: boolean
+  image?: string
+  author?: string | string[]
+  date?: string
+  tags?: string[]
+}
+
 export interface ArticleNode {
-  pathname: string
+  path: string
   title: string
+  label?: string
   icon: string
   children: ArticleNode[]
 }
 
-/** Build a tree from a flat sorted list of articles based on pathname hierarchy */
-export function buildArticleTree(
-  articles: { pathname: string; title: string; icon: string }[],
-) {
-  const nodeMap = new Map<string, ArticleNode>()
-
-  for (const article of articles) {
-    nodeMap.set(article.pathname, {
-      pathname: article.pathname,
-      title: article.title,
-      icon: article.icon,
-      children: [],
-    })
-  }
-
-  const roots: ArticleNode[] = []
-
-  for (const article of articles) {
-    const node = nodeMap.get(article.pathname)!
-    const trimmed = article.pathname.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
+/**
+ * A contiguous section of root articles sharing the same `group` label.
+ * `name: undefined` represents the leading ungrouped section (at most one).
+ */
+export interface ArticleGroup {
+  name?: string
+  nodes: ArticleNode[]
 }

package/build/website/models/toc.ts

@@ -0,0 +1,5 @@
+export interface TocItem {
+  url: string
+  title: string
+  depth: number
+}

package/build/website/plugins/rehype-task-list-a11y.ts

@@ -0,0 +1,33 @@
+import { visit } from "unist-util-visit"
+
+interface HastNode {
+  type: string
+  tagName?: string
+  properties?: Record<string, unknown>
+  children?: HastNode[]
+}
+
+/** Give each GFM task-list checkbox an accessible name so screen readers and
+ * axe-based audits don't flag them as form controls without labels. */
+export function rehypeTaskListA11y() {
+  return (tree: HastNode) => {
+    visit(tree, "element", (node: HastNode) => {
+      if (node.tagName !== "li") return
+      const classes = node.properties?.className
+      const hasTaskClass =
+        Array.isArray(classes) && classes.includes("task-list-item")
+      if (!hasTaskClass) return
+
+      for (const child of node.children ?? []) {
+        if (child.type !== "element") continue
+        if (child.tagName !== "input") continue
+        if (child.properties?.type !== "checkbox") continue
+        child.properties = {
+          ...child.properties,
+          ariaLabel: child.properties?.checked ? "Completed task" : "Task",
+        }
+        break
+      }
+    })
+  }
+}

package/build/website/plugins/remark-ansi.ts

@@ -172,6 +172,7 @@ function applyParams(state: AnsiState, params: ReadonlyArray<number>) {
 
 /** Convert a string containing ANSI escape sequences into HTML with inline styles */
 export function ansiToHtml(input: string): string {
+  // oxlint-disable-next-line no-control-regex -- ANSI escape sequences start with U+001B
   const sgr = /\u001b\[([0-9;]*)m/g
   const state = makeDefaultState()
   const parts: string[] = []

package/build/website/plugins/remark-image.ts

@@ -1,25 +1,34 @@
-import { dirname, relative, resolve } from "node:path"
-import type { Image, Root } from "mdast"
+import type { Root } from "mdast"
 import type { Plugin } from "unified"
 import { visit } from "unist-util-visit"
+import { resolveAssetPath } from "../helpers/resolve-asset-path.ts"
 
-/** Remark plugin that resolves relative image paths to URLs serveable by Vite */
+/** Remark plugin that resolves relative image paths and unwraps image-only paragraphs */
 export const remarkImage: Plugin<
   [{ filePath: string; root: string }],
   Root
 > = ({ filePath, root }) => {
-  const fileDir = dirname(filePath)
-
   return tree => {
-    visit(tree, "image", (node: Image) => {
-      if (
-        node.url.startsWith("http") ||
-        node.url.startsWith("/") ||
-        node.url.startsWith("data:")
+    visit(tree, "image", node => {
+      node.url = resolveAssetPath(node.url, filePath, root)
+    })
+
+    visit(tree, "paragraph", (node, index, parent) => {
+      if (!parent || typeof index !== "number") return
+      const isImageOnly = node.children.every(
+        child =>
+          child.type === "image" ||
+          child.type === "imageReference" ||
+          child.type === "break" ||
+          (child.type === "text" && child.value.trim() === ""),
+      )
+      if (!isImageOnly) return
+      const images = node.children.filter(
+        child => child.type === "image" || child.type === "imageReference",
       )
-        return
-      const absolute = resolve(fileDir, node.url)
-      node.url = "/" + relative(root, absolute)
+      if (images.length === 0) return
+      parent.children.splice(index, 1, ...images)
+      return index + images.length
     })
   }
 }

package/build/website/plugins/vite-livemark.ts

@@ -0,0 +1,91 @@
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { Plugin } from "vite"
+
+/** Sub-directories of `website/` that participate in the override mechanism. */
+export const OVERRIDE_SUBDIRS: readonly string[] = [
+  "components",
+  "elements",
+  "styles",
+]
+
+export interface LivemarkOptions {
+  defaultsRoot: string
+  overridesRoot: string
+  subdirs: string[]
+  configPath: string
+}
+
+/** Livemark dev/build integration:
+ * - Redirects imports that land in `<defaultsRoot>/<subdir>/` to the matching
+ *   user file under `<overridesRoot>/<subdir>/` when it exists.
+ * - Watches `livemark.config.ts` and `.livemark/**` so edits, additions and
+ *   deletions trigger the right reload without manual restart. */
+export function livemark(opts: LivemarkOptions): Plugin {
+  const EXT_RE = /\.(tsx|ts|jsx|js|css)(\?|$)/
+  return {
+    name: "livemark",
+    enforce: "pre",
+    async resolveId(id, importer, options) {
+      if (!importer || !EXT_RE.test(id)) return null
+      const resolved = await this.resolve(id, importer, {
+        ...options,
+        skipSelf: true,
+      })
+      if (!resolved) return null
+      const queryIdx = resolved.id.indexOf("?")
+      const path =
+        queryIdx === -1 ? resolved.id : resolved.id.slice(0, queryIdx)
+      const query = queryIdx === -1 ? "" : resolved.id.slice(queryIdx)
+      for (const subdir of opts.subdirs) {
+        const defaultsSubdir = `${join(opts.defaultsRoot, subdir)}/`
+        if (!path.startsWith(defaultsSubdir)) continue
+        const rel = path.slice(defaultsSubdir.length)
+        const userPath = join(opts.overridesRoot, subdir, rel)
+        if (existsSync(userPath)) return userPath + query
+        return null
+      }
+      return null
+    },
+    configureServer(server) {
+      server.watcher.add(opts.configPath)
+      server.watcher.add(join(opts.overridesRoot, "**/*"))
+
+      const overrideRoots = opts.subdirs.map(
+        subdir => `${join(opts.overridesRoot, subdir)}/`,
+      )
+      const routesRoot = `${join(opts.overridesRoot, "routes")}/`
+
+      const onChange = (file: string) => {
+        if (file === opts.configPath) {
+          server.restart()
+          return
+        }
+
+        if (file.startsWith(routesRoot)) {
+          server.restart()
+          return
+        }
+
+        for (let i = 0; i < opts.subdirs.length; i++) {
+          const root = overrideRoots[i]
+          if (!root || !file.startsWith(root)) continue
+          const rel = file.slice(root.length)
+          const subdir = opts.subdirs[i]
+          if (!subdir) continue
+          const defaultPath = join(opts.defaultsRoot, subdir, rel)
+          const mod = server.moduleGraph.getModuleById(defaultPath)
+          if (mod) server.moduleGraph.invalidateModule(mod)
+          server.ws.send({ type: "full-reload" })
+          return
+        }
+      }
+
+      server.watcher.on("add", onChange)
+      server.watcher.on("unlink", onChange)
+      server.watcher.on("change", file => {
+        if (file === opts.configPath) server.restart()
+      })
+    },
+  }
+}

package/build/website/routeTree.gen.ts

@@ -9,10 +9,10 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
-import { Route as SplatRouteImport } from './routes/$'
-import { Route as IndexRouteImport } from './routes/index'
+import { Route as splatRouteImport } from './routes/$'
+import { Route as IndexRouteImport } from './../.livemark/routes/index'
 
-const SplatRoute = SplatRouteImport.update({
+const splatRoute = splatRouteImport.update({
   id: '/$',
   path: '/$',
   getParentRoute: () => rootRouteImport,
@@ -25,16 +25,16 @@ const IndexRoute = IndexRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
-  '/$': typeof SplatRoute
+  '/$': typeof splatRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
-  '/$': typeof SplatRoute
+  '/$': typeof splatRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
-  '/$': typeof SplatRoute
+  '/$': typeof splatRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
@@ -46,7 +46,7 @@ export interface FileRouteTypes {
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
-  SplatRoute: typeof SplatRoute
+  splatRoute: typeof splatRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -55,7 +55,7 @@ declare module '@tanstack/react-router' {
       id: '/$'
       path: '/$'
       fullPath: '/$'
-      preLoaderRoute: typeof SplatRouteImport
+      preLoaderRoute: typeof splatRouteImport
       parentRoute: typeof rootRouteImport
     }
     '/': {
@@ -70,7 +70,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
-  SplatRoute: SplatRoute,
+  splatRoute: splatRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)

package/build/website/routes/$.tsx

@@ -1,149 +1,92 @@
-import { MDXContent } from "@content-collections/mdx/react"
-import { createFileRoute, notFound } from "@tanstack/react-router"
-import { sortedArticles } from "../helpers/articles.ts"
-import { Callout } from "../components/Callout.tsx"
-import { Columns, Column } from "../components/Columns.tsx"
-import { Card, Cards } from "../components/Cards.tsx"
-import { CodeBlock } from "../components/CodeBlock.tsx"
-import { headingComponents } from "../components/Heading.tsx"
-import { Calendar } from "lucide-react"
-import { CodeTabs } from "../components/CodeTabs.tsx"
-import { ContentTab } from "../components/ContentTab.tsx"
-import { ContentTabs } from "../components/ContentTabs.tsx"
-import { Details } from "../components/Details.tsx"
-import { FileTree } from "../components/FileTree.tsx"
-import { InlineIcon } from "../components/InlineIcon.tsx"
-import { Abbr } from "../components/Abbr.tsx"
-import { FootnoteRef } from "../components/FootnoteRef.tsx"
+import { createFileRoute, notFound, redirect } from "@tanstack/react-router"
 import {
-  DefinitionList,
-  DefinitionTerm,
-  DefinitionDetail,
-} from "../components/DefinitionList.tsx"
-import { AnsiCode } from "../components/AnsiCode.tsx"
-import { InlineBadge } from "../components/InlineBadge.tsx"
-import { LinkButton } from "../components/LinkButton.tsx"
-import { Mermaid } from "../components/Mermaid.tsx"
-import { PackageTabs } from "../components/PackageTabs.tsx"
-import { SoundCloud } from "../components/SoundCloud.tsx"
-import { YouTube } from "../components/YouTube.tsx"
-import { InlineToc } from "../components/InlineToc.tsx"
-import { PageToolbar } from "../components/PageToolbar.tsx"
-import { PrevNext } from "../components/PrevNext.tsx"
-import { Toc } from "../components/Toc.tsx"
-import { ZoomImage } from "../components/ZoomImage.tsx"
-import { Separator } from "../elements/separator.tsx"
-import { TocContext } from "../helpers/toc-context.ts"
-import {
-  SortableTable,
-  TableHeader,
-  TableBody,
-  TableRow,
-  TableHead,
-  TableCell,
-} from "../components/SortableTable.tsx"
+  currentSection,
+  firstArticle,
+  homeArticle,
+  sortedArticles,
+} from "../content/article.ts"
+import { sectionTags } from "../content/tag.ts"
+import { Article } from "../components/Article.tsx"
+import { BlogIndex } from "../components/BlogIndex.tsx"
+import { ChangelogIndex } from "../components/ChangelogIndex.tsx"
+import { TagIndex } from "../components/TagIndex.tsx"
+import markdownCss from "../styles/markdown.css?url"
 
 export const Route = createFileRoute("/$")({
   loader: ({ params }) => {
+    if (!params._splat) {
+      if (homeArticle) return { ...homeArticle, sidebar: homeArticle.sidebar }
+      if (!firstArticle) throw notFound()
+      throw redirect({
+        to: "/$",
+        params: { _splat: firstArticle.path.replace(/^\/|\/$/g, "") },
+      })
+    }
     const splat = `/${params._splat}/`
-    const article = sortedArticles.find(a => a.pathname === splat)
-    if (!article) throw notFound()
-    return article
+    const article = sortedArticles.find(a => a.path === splat)
+    if (article) return article
+
+    const section = currentSection(splat)
+    if (section?.type === "changelog" && section.prefix === splat) {
+      return {
+        changelogIndex: true as const,
+        sectionPrefix: section.prefix,
+        title: section.title,
+        sidebar: true,
+      }
+    }
+    if (section?.type === "blog") {
+      if (section.prefix === splat) {
+        return {
+          blogIndex: true as const,
+          sectionPrefix: section.prefix,
+          title: section.title,
+          sidebar: true,
+        }
+      }
+
+      const tagMatch = splat.match(
+        new RegExp(`^${section.prefix}tags/([^/]+)/$`),
+      )
+      const tag = tagMatch?.[1]
+      if (tag) {
+        const tagMap = sectionTags.get(section.prefix)
+        if (tagMap?.has(tag)) {
+          return {
+            tagPage: true as const,
+            sectionPrefix: section.prefix,
+            tag,
+            title: `Posts tagged '${tag}'`,
+            sidebar: true,
+          }
+        }
+      }
+    }
+
+    throw notFound()
   },
   head: ({ loaderData }) => ({
     meta: [
       ...(loaderData ? [{ title: loaderData.title }] : []),
-      ...(loaderData?.description
+      ...("description" in loaderData && loaderData.description
         ? [{ name: "description", content: loaderData.description }]
         : []),
     ],
+    links: [{ rel: "stylesheet", href: markdownCss }],
   }),
   component: Component,
 })
 
 function Component() {
-  const article = Route.useLoaderData()
-  const lastUpdated = formatDate(article.lastUpdated)
-
-  const H1 = (props: React.HTMLAttributes<HTMLHeadingElement>) => (
-    <>
-      <h1 {...props}>
-        {props.id ? (
-          <a href={`#${props.id}`}>{props.children}</a>
-        ) : (
-          props.children
-        )}
-      </h1>
-      {lastUpdated && (
-        <p className="flex items-center gap-1.5 text-sm text-muted-foreground !-mt-4 !mb-6">
-          <Calendar className="size-3.5" />
-          Last updated {lastUpdated}
-        </p>
-      )}
-    </>
-  )
-
-  return (
-    <TocContext.Provider value={article.toc}>
-      <div className="flex flex-1 gap-10 p-6 md:p-10">
-        <div className="flex-1 min-w-0 mx-auto max-w-3xl">
-          <div className="prose dark:prose-invert max-w-none">
-            <MDXContent
-              code={article.mdx}
-              components={{
-                hr: Separator,
-                img: ZoomImage,
-                pre: CodeBlock,
-                table: SortableTable,
-                thead: TableHeader,
-                tbody: TableBody,
-                tr: TableRow,
-                th: TableHead,
-                td: TableCell,
-                a: FootnoteRef,
-                Abbr,
-                AnsiCode,
-                Callout,
-                Card,
-                Cards,
-                Column,
-                Columns,
-                CodeTabs,
-                ContentTab,
-                ContentTabs,
-                DefinitionDetail,
-                DefinitionList,
-                DefinitionTerm,
-                Details,
-                FileTree,
-                InlineBadge,
-                InlineIcon,
-                InlineToc,
-                LinkButton,
-                Mermaid,
-                PackageTabs,
-                SoundCloud,
-                YouTube,
-                ...headingComponents,
-                h1: H1,
-              }}
-            />
-          </div>
-          <PrevNext pathname={article.pathname} />
-        </div>
-        <Toc items={article.toc}>
-          <PageToolbar filePath={article.filePath} content={article.content} />
-        </Toc>
-      </div>
-    </TocContext.Provider>
-  )
-}
-
-function formatDate(iso?: string) {
-  if (!iso) return undefined
-  return new Date(iso).toLocaleDateString("en-US", {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  })
+  const data = Route.useLoaderData()
+  if ("blogIndex" in data) {
+    return <BlogIndex sectionPrefix={data.sectionPrefix} />
+  }
+  if ("changelogIndex" in data) {
+    return <ChangelogIndex sectionPrefix={data.sectionPrefix} />
+  }
+  if ("tagPage" in data) {
+    return <TagIndex sectionPrefix={data.sectionPrefix} tag={data.tag} />
+  }
+  return <Article article={data} />
 }