livemark 0.2.0 → 0.7.0

package/build/website/helpers/toc.ts

@@ -0,0 +1,46 @@
+import GithubSlugger from "github-slugger"
+import type { TocItem } from "../models/toc.ts"
+
+const CUSTOM_ID_PATTERN = /\s*\[#([^\]]+)\]\s*$/
+const TOC_HIDDEN_PATTERN = /\s*\[!toc\]\s*$/
+const TOC_ONLY_PATTERN = /\s*\[toc\]\s*$/
+const STEP_PATTERN = /\s*\[step\]\s*$/
+
+/** Extract TOC headings from raw markdown content */
+export function extractToc(content: string): TocItem[] {
+  const slugger = new GithubSlugger()
+  const items: TocItem[] = []
+  const headingRegex = /^(#{2,4})\s+(.+)$/
+  const lines = content.split("\n")
+  let inCodeBlock = false
+
+  for (const line of lines) {
+    if (line.startsWith("```") || line.startsWith("````")) {
+      inCodeBlock = !inCodeBlock
+      continue
+    }
+    if (inCodeBlock) continue
+
+    const match = headingRegex.exec(line)
+    if (!match) continue
+
+    const depth = match[1]!.length
+    const rawTitle = match[2]!
+
+    if (TOC_HIDDEN_PATTERN.test(rawTitle)) continue
+    if (STEP_PATTERN.test(rawTitle)) continue
+
+    const idMatch = CUSTOM_ID_PATTERN.exec(rawTitle)
+    const title = rawTitle
+      .replace(CUSTOM_ID_PATTERN, "")
+      .replace(TOC_ONLY_PATTERN, "")
+      .replace(STEP_PATTERN, "")
+      .replace(/\*\*(.+?)\*\*/g, "$1")
+      .replace(/`(.+?)`/g, "$1")
+    const slug = idMatch?.[1] ?? slugger.slug(title)
+
+    items.push({ url: `#${slug}`, title, depth })
+  }
+
+  return items
+}

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

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vite-plus/test"
+import { extractToc } from "./toc.ts"
+
+describe("extractToc", () => {
+  it("should extract headings with auto-generated slugs", () => {
+    const content = "## Introduction\n\n### Getting Started"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#introduction", title: "Introduction", depth: 2 },
+      { url: "#getting-started", title: "Getting Started", depth: 3 },
+    ])
+  })
+
+  it("should use custom id when [#custom-id] syntax is present", () => {
+    const content = "## My Section [#custom-id]\n\n### Sub Section"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#custom-id", title: "My Section", depth: 2 },
+      { url: "#sub-section", title: "Sub Section", depth: 3 },
+    ])
+  })
+
+  it("should strip [#id] from the displayed title", () => {
+    const content = "## Installation [#install]"
+    const toc = extractToc(content)
+    expect(toc).toEqual([{ url: "#install", title: "Installation", depth: 2 }])
+  })
+
+  it("should handle inline formatting with custom ids", () => {
+    const content = "## **Bold** Title [#bold-title]"
+    const toc = extractToc(content)
+    expect(toc).toEqual([{ url: "#bold-title", title: "Bold Title", depth: 2 }])
+  })
+
+  it("should handle code formatting with custom ids", () => {
+    const content = "## `config` Options [#config-opts]"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#config-opts", title: "config Options", depth: 2 },
+    ])
+  })
+
+  it("should skip h1 headings", () => {
+    const content = "# Title\n\n## Section"
+    const toc = extractToc(content)
+    expect(toc).toEqual([{ url: "#section", title: "Section", depth: 2 }])
+  })
+
+  it("should exclude [step] headings from TOC", () => {
+    const content =
+      "## Overview\n\n### Install Dependencies [step]\n\n### Configure Project [step]"
+    const toc = extractToc(content)
+    expect(toc).toEqual([{ url: "#overview", title: "Overview", depth: 2 }])
+  })
+
+  it("should skip headings with [!toc] annotation", () => {
+    const content = "## Visible\n\n## Hidden From TOC [!toc]\n\n## Also Visible"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#visible", title: "Visible", depth: 2 },
+      { url: "#also-visible", title: "Also Visible", depth: 2 },
+    ])
+  })
+
+  it("should include [toc] headings with annotation stripped from title", () => {
+    const content = "## Regular\n\n## TOC Only [toc]\n\n## Another"
+    const toc = extractToc(content)
+    expect(toc).toEqual([
+      { url: "#regular", title: "Regular", depth: 2 },
+      { url: "#toc-only", title: "TOC Only", depth: 2 },
+      { url: "#another", title: "Another", depth: 2 },
+    ])
+  })
+})

package/build/website/hooks/in-view.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+
+export function useInView() {
+  const [isVisible, setIsVisible] = useState(false)
+  const elementRef = useRef<Element | null>(null)
+
+  const ref = useCallback((node: Element | null) => {
+    elementRef.current = node
+  }, [])
+
+  useEffect(() => {
+    const node = elementRef.current
+    if (!node) return
+
+    const observer = new IntersectionObserver(
+      entries => {
+        if (entries[0]?.isIntersecting) {
+          setIsVisible(true)
+          observer.disconnect()
+        }
+      },
+      { threshold: 0.1 },
+    )
+
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [])
+
+  return { ref, isVisible }
+}

package/build/website/hooks/media.ts

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/build/website/models/article.ts

@@ -0,0 +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 {
+  path: string
+  title: string
+  label?: string
+  icon: string
+  children: ArticleNode[]
+}
+
+/**
+ * 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-inline-code.ts

@@ -0,0 +1,107 @@
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+import {
+  type BundledLanguage,
+  bundledLanguages,
+  getSingletonHighlighter,
+} from "shiki"
+
+interface HastText {
+  type: "text"
+  value: string
+}
+
+type PropertyValue =
+  | boolean
+  | number
+  | string
+  | null
+  | undefined
+  | Array<string | number>
+
+interface HastElement {
+  type: "element"
+  tagName: string
+  properties: Record<string, PropertyValue>
+  children: (HastElement | HastText)[]
+}
+
+interface HastRoot {
+  type: "root"
+  children: (HastElement | HastText)[]
+}
+
+type HastNode = HastRoot | HastElement | HastText
+
+const LANG_PREFIX = /^\{:(\w+)\}/
+
+function isBundledLanguage(lang: string): lang is BundledLanguage {
+  return lang in bundledLanguages
+}
+
+/** Rehype plugin that applies Shiki syntax highlighting to inline code spans with a `{:lang}` prefix. */
+export const rehypeInlineCode: Plugin<[], HastRoot> = () => {
+  return async (tree: HastRoot) => {
+    const highlighter = await getSingletonHighlighter({
+      themes: ["catppuccin-latte", "catppuccin-mocha"],
+      langs: [],
+    })
+
+    const nodes: {
+      node: HastElement
+      lang: BundledLanguage
+      code: string
+    }[] = []
+
+    visit(
+      tree,
+      "element",
+      (
+        node: HastNode,
+        _index: number | undefined,
+        parent: HastNode | undefined,
+      ) => {
+        if (node.type !== "element") return
+        if (node.tagName !== "code") return
+        if (parent && parent.type === "element" && parent.tagName === "pre")
+          return
+
+        const textChild = node.children[0]
+        if (!textChild || textChild.type !== "text") return
+
+        const match = LANG_PREFIX.exec(textChild.value)
+        if (!match) return
+
+        const lang = match[1]!
+        if (!isBundledLanguage(lang)) return
+
+        const code = textChild.value.slice(match[0].length)
+        nodes.push({ node, lang, code })
+      },
+    )
+
+    for (const { node, lang, code } of nodes) {
+      await highlighter.loadLanguage(lang)
+      const result = highlighter.codeToHast(code, {
+        themes: { light: "catppuccin-latte", dark: "catppuccin-mocha" },
+        lang,
+      })
+
+      const pre = result.children[0]
+      if (pre && pre.type === "element" && "children" in pre) {
+        const codeEl = pre.children[0]
+        if (codeEl && codeEl.type === "element" && "children" in codeEl) {
+          node.children = codeEl.children.filter(
+            (c): c is HastElement | HastText =>
+              c.type === "element" || c.type === "text",
+          )
+          node.properties = {
+            ...node.properties,
+            className: "shiki-inline",
+            style: codeEl.properties?.style,
+          }
+        }
+      }
+    }
+  }
+}

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-abbr.ts

@@ -0,0 +1,46 @@
+import type { Root } from "mdast"
+import type { TextDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+/** Walk a mdast tree and convert :abbr text directives into Abbr JSX elements */
+export function transformAbbrDirectives(tree: Root) {
+  visit(tree, "textDirective", (node: TextDirective, index, parent) => {
+    if (node.name !== "abbr" || index === undefined || !parent) return
+
+    const text = node.children
+      .map(c => ("value" in c ? String(c.value) : ""))
+      .join("")
+
+    const title = node.attributes?.title ?? ""
+
+    const jsxNode = {
+      type: "mdxJsxTextElement" as const,
+      name: "Abbr",
+      attributes: [
+        {
+          type: "mdxJsxAttribute" as const,
+          name: "text",
+          value: text,
+        },
+        {
+          type: "mdxJsxAttribute" as const,
+          name: "title",
+          value: title,
+        },
+      ],
+      children: [],
+      data: { _mdxExplicitJsx: true },
+    }
+
+    // @ts-expect-error mdxJsxTextElement is not in mdast types
+    parent.children.splice(index, 1, jsxNode)
+  })
+}
+
+/** Remark plugin that converts :abbr text directives into Abbr JSX elements */
+export const remarkAbbr: Plugin<[], Root> = () => {
+  return tree => {
+    transformAbbrDirectives(tree)
+  }
+}

package/build/website/plugins/remark-abbr.unit.ts

@@ -0,0 +1,99 @@
+import type { Root } from "mdast"
+import type { TextDirective } from "mdast-util-directive"
+import { describe, expect, it } from "vite-plus/test"
+import { transformAbbrDirectives } from "./remark-abbr.ts"
+
+function makeTextDirective(
+  name: string,
+  text: string,
+  attributes?: Record<string, string>,
+): TextDirective {
+  return {
+    type: "textDirective",
+    name,
+    attributes: attributes ?? {},
+    children: [{ type: "text", value: text }],
+  }
+}
+
+function makeTree(...children: Root["children"]): Root {
+  return { type: "root", children }
+}
+
+describe("transformAbbrDirectives", () => {
+  function process(tree: Root) {
+    transformAbbrDirectives(tree)
+    return tree
+  }
+
+  it("should convert :abbr directive to Abbr JSX element", () => {
+    const directive = makeTextDirective("abbr", "HTML", {
+      title: "HyperText Markup Language",
+    })
+    const tree = process(
+      makeTree({
+        type: "paragraph",
+        children: [directive],
+      }),
+    )
+
+    const paragraph = tree.children[0]
+    if (!paragraph || paragraph.type !== "paragraph")
+      throw new Error("Expected paragraph")
+    const node = paragraph.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxTextElement",
+      name: "Abbr",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "text", value: "HTML" },
+        {
+          type: "mdxJsxAttribute",
+          name: "title",
+          value: "HyperText Markup Language",
+        },
+      ],
+      children: [],
+    })
+  })
+
+  it("should use empty string when title is not provided", () => {
+    const directive = makeTextDirective("abbr", "CSS")
+    const tree = process(
+      makeTree({
+        type: "paragraph",
+        children: [directive],
+      }),
+    )
+
+    const paragraph = tree.children[0]
+    if (!paragraph || paragraph.type !== "paragraph")
+      throw new Error("Expected paragraph")
+    const node = paragraph.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxTextElement",
+      name: "Abbr",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "text", value: "CSS" },
+        { type: "mdxJsxAttribute", name: "title", value: "" },
+      ],
+    })
+  })
+
+  it("should ignore non-abbr text directives", () => {
+    const directive = makeTextDirective("other", "Text")
+    const tree = process(
+      makeTree({
+        type: "paragraph",
+        children: [directive],
+      }),
+    )
+
+    const paragraph = tree.children[0]
+    if (!paragraph || paragraph.type !== "paragraph")
+      throw new Error("Expected paragraph")
+    expect(paragraph.children[0]).toMatchObject({
+      type: "textDirective",
+      name: "other",
+    })
+  })
+})