livemark 0.2.0 → 0.7.0

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

@@ -0,0 +1,49 @@
+import type { Paragraph, Root } from "mdast"
+import type { ContainerDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+/** Remark plugin that converts :::details directives into collapsible details/summary elements */
+export const remarkDetails: Plugin<[], Root> = () => {
+  return tree => {
+    visit(
+      tree,
+      "containerDirective",
+      (node: ContainerDirective, index, parent) => {
+        if (node.name !== "details" || index === undefined || !parent) return
+
+        const labelParagraph = node.children.find(
+          (child): child is Paragraph =>
+            child.type === "paragraph" && !!child.data?.directiveLabel,
+        )
+
+        const summary = labelParagraph
+          ? labelParagraph.children
+              .map(c => ("value" in c ? String(c.value) : ""))
+              .join("")
+          : "Details"
+
+        const body = node.children.filter(
+          child => !(child.type === "paragraph" && child.data?.directiveLabel),
+        )
+
+        const jsxNode = {
+          type: "mdxJsxFlowElement" as const,
+          name: "Details",
+          attributes: [
+            {
+              type: "mdxJsxAttribute" as const,
+              name: "summary",
+              value: summary,
+            },
+          ],
+          children: body,
+          data: { _mdxExplicitJsx: true },
+        }
+
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        parent.children.splice(index, 1, jsxNode)
+      },
+    )
+  }
+}

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

@@ -0,0 +1,89 @@
+import type { List, ListItem, Paragraph, Root, Text } from "mdast"
+import type { ContainerDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit, SKIP } from "unist-util-visit"
+
+interface TreeItem {
+  name: string
+  isDir: boolean
+  children?: TreeItem[]
+}
+
+/** Extract tree items from a mdast list node */
+export function parseList(list: List): TreeItem[] {
+  const items: TreeItem[] = []
+
+  for (const listItem of list.children) {
+    if (listItem.type !== "listItem") continue
+    const item = parseListItem(listItem)
+    if (item) items.push(item)
+  }
+
+  return items
+}
+
+function parseListItem(listItem: ListItem): TreeItem | undefined {
+  const paragraph = listItem.children.find(
+    (child): child is Paragraph => child.type === "paragraph",
+  )
+  if (!paragraph) return undefined
+
+  const textContent = paragraph.children
+    .filter((c): c is Text => c.type === "text")
+    .map(c => c.value)
+    .join("")
+    .trim()
+
+  if (!textContent) return undefined
+
+  const isDir = textContent.endsWith("/")
+  const name = isDir ? textContent.slice(0, -1) : textContent
+
+  const nestedList = listItem.children.find(
+    (child): child is List => child.type === "list",
+  )
+
+  const children = nestedList ? parseList(nestedList) : undefined
+
+  return { name, isDir, children }
+}
+
+/** Remark plugin that converts :::filetree directives into FileTree JSX elements */
+export const remarkFiletree: Plugin<[], Root> = () => {
+  return tree => {
+    visit(
+      tree,
+      "containerDirective",
+      (node: ContainerDirective, index, parent) => {
+        if (node.name !== "filetree" || index === undefined || !parent) return
+
+        const lists = node.children.filter(
+          (child): child is List => child.type === "list",
+        )
+
+        const treeItems: TreeItem[] = []
+        for (const list of lists) {
+          treeItems.push(...parseList(list))
+        }
+
+        const jsxNode = {
+          type: "mdxJsxFlowElement" as const,
+          name: "FileTree",
+          attributes: [
+            {
+              type: "mdxJsxAttribute" as const,
+              name: "tree",
+              value: JSON.stringify(treeItems),
+            },
+          ],
+          children: [],
+          data: { _mdxExplicitJsx: true },
+        }
+
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        parent.children[index] = jsxNode
+        return SKIP
+      },
+    )
+  }
+}

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

@@ -0,0 +1,137 @@
+import type { List, ListItem, Paragraph, Text } from "mdast"
+import { describe, expect, it } from "vite-plus/test"
+import { parseList } from "./remark-filetree.ts"
+
+function text(value: string): Text {
+  return { type: "text", value }
+}
+
+function paragraph(...children: Text[]): Paragraph {
+  return { type: "paragraph", children }
+}
+
+function listItem(...children: (Paragraph | List)[]): ListItem {
+  return { type: "listItem", children, spread: false }
+}
+
+function list(...children: ListItem[]): List {
+  return { type: "list", children, ordered: false, spread: false }
+}
+
+describe("parseList", () => {
+  it("should parse flat file entries", () => {
+    const input = list(
+      listItem(paragraph(text("package.json"))),
+      listItem(paragraph(text("tsconfig.json"))),
+    )
+
+    expect(parseList(input)).toEqual([
+      { name: "package.json", isDir: false },
+      { name: "tsconfig.json", isDir: false },
+    ])
+  })
+
+  it("should detect directories by trailing slash", () => {
+    const input = list(
+      listItem(paragraph(text("src/"))),
+      listItem(paragraph(text("README.md"))),
+    )
+
+    expect(parseList(input)).toEqual([
+      { name: "src", isDir: true },
+      { name: "README.md", isDir: false },
+    ])
+  })
+
+  it("should parse nested directory structures", () => {
+    const input = list(
+      listItem(
+        paragraph(text("src/")),
+        list(
+          listItem(paragraph(text("index.ts"))),
+          listItem(
+            paragraph(text("components/")),
+            list(listItem(paragraph(text("Button.tsx")))),
+          ),
+        ),
+      ),
+    )
+
+    expect(parseList(input)).toEqual([
+      {
+        name: "src",
+        isDir: true,
+        children: [
+          { name: "index.ts", isDir: false },
+          {
+            name: "components",
+            isDir: true,
+            children: [{ name: "Button.tsx", isDir: false }],
+          },
+        ],
+      },
+    ])
+  })
+
+  it("should skip list items without text content", () => {
+    const emptyItem: ListItem = {
+      type: "listItem",
+      children: [],
+      spread: false,
+    }
+    const input = list(emptyItem, listItem(paragraph(text("file.ts"))))
+
+    expect(parseList(input)).toEqual([{ name: "file.ts", isDir: false }])
+  })
+
+  it("should trim whitespace from names", () => {
+    const input = list(listItem(paragraph(text("  file.ts  "))))
+
+    expect(parseList(input)).toEqual([{ name: "file.ts", isDir: false }])
+  })
+
+  it("should handle deeply nested structures", () => {
+    const input = list(
+      listItem(
+        paragraph(text("a/")),
+        list(
+          listItem(
+            paragraph(text("b/")),
+            list(
+              listItem(
+                paragraph(text("c/")),
+                list(listItem(paragraph(text("deep.ts")))),
+              ),
+            ),
+          ),
+        ),
+      ),
+    )
+
+    expect(parseList(input)).toEqual([
+      {
+        name: "a",
+        isDir: true,
+        children: [
+          {
+            name: "b",
+            isDir: true,
+            children: [
+              {
+                name: "c",
+                isDir: true,
+                children: [{ name: "deep.ts", isDir: false }],
+              },
+            ],
+          },
+        ],
+      },
+    ])
+  })
+
+  it("should return undefined children for directories without nested list", () => {
+    const input = list(listItem(paragraph(text("empty-dir/"))))
+
+    expect(parseList(input)).toEqual([{ name: "empty-dir", isDir: true }])
+  })
+})

package/build/website/plugins/remark-github-callout.ts

@@ -0,0 +1,71 @@
+import type { Blockquote, Paragraph, Root, Text } from "mdast"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+const typeMap: Record<string, string> = {
+  NOTE: "note",
+  TIP: "tip",
+  WARNING: "warning",
+  CAUTION: "danger",
+  IMPORTANT: "info",
+}
+
+const calloutPattern = /^\[!(\w+)\]\s*/
+
+/** Remark plugin that converts GitHub-style blockquote callouts into Callout JSX elements */
+export const remarkGithubCallout: Plugin<[], Root> = () => {
+  return tree => {
+    visit(tree, "blockquote", (node: Blockquote, index, parent) => {
+      if (!parent || index === undefined || node.children.length === 0) return
+
+      const first = node.children[0]
+      if (first?.type !== "paragraph" || first.children.length === 0) return
+
+      const firstInline = first.children[0]
+      if (firstInline?.type !== "text") return
+
+      const match = calloutPattern.exec(firstInline.value)
+      if (!match) return
+
+      const rawType = match[1]
+      if (!rawType) return
+
+      const calloutType = typeMap[rawType]
+      if (!calloutType) return
+
+      const remainingText = firstInline.value.slice(match[0].length)
+
+      const updatedFirstChildren = [
+        ...(remainingText
+          ? [{ type: "text" as const, value: remainingText } satisfies Text]
+          : []),
+        ...first.children.slice(1),
+      ]
+
+      const body =
+        updatedFirstChildren.length > 0
+          ? [
+              { ...first, children: updatedFirstChildren } satisfies Paragraph,
+              ...node.children.slice(1),
+            ]
+          : node.children.slice(1)
+
+      const jsxNode = {
+        type: "mdxJsxFlowElement" as const,
+        name: "Callout",
+        attributes: [
+          {
+            type: "mdxJsxAttribute" as const,
+            name: "type",
+            value: calloutType,
+          },
+        ],
+        children: body,
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      parent.children.splice(index, 1, jsxNode)
+    })
+  }
+}

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

@@ -0,0 +1,42 @@
+import type { Root } from "mdast"
+import type { TextDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+/** Remark plugin that converts :icon text directives into InlineIcon JSX elements */
+export const remarkIcon: Plugin<[], Root> = () => {
+  return tree => {
+    visit(tree, "textDirective", (node: TextDirective, index, parent) => {
+      if (node.name !== "icon" || index === undefined || !parent) return
+
+      const name = node.attributes?.name
+      if (!name) return
+
+      const className = node.attributes?.className
+
+      const attributes = [
+        { type: "mdxJsxAttribute" as const, name: "name", value: name },
+        ...(className
+          ? [
+              {
+                type: "mdxJsxAttribute" as const,
+                name: "className",
+                value: className,
+              },
+            ]
+          : []),
+      ]
+
+      const jsxNode = {
+        type: "mdxJsxTextElement" as const,
+        name: "InlineIcon",
+        attributes,
+        children: [],
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxTextElement is not in mdast types
+      parent.children[index] = jsxNode
+    })
+  }
+}

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

@@ -0,0 +1,34 @@
+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 and unwraps image-only paragraphs */
+export const remarkImage: Plugin<
+  [{ filePath: string; root: string }],
+  Root
+> = ({ filePath, root }) => {
+  return tree => {
+    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",
+      )
+      if (images.length === 0) return
+      parent.children.splice(index, 1, ...images)
+      return index + images.length
+    })
+  }
+}

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

@@ -0,0 +1,62 @@
+import type { Root } from "mdast"
+import type { LeafDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+/** Walk a mdast tree and convert media leaf directives into JSX embed elements */
+export function transformMediaDirectives(tree: Root) {
+  visit(tree, "leafDirective", (node: LeafDirective, index, parent) => {
+    if (
+      (node.name !== "video" && node.name !== "audio") ||
+      index === undefined ||
+      !parent
+    )
+      return
+
+    const type = node.attributes?.type
+    if (!type) return
+
+    if (node.name === "video" && type === "youtube") {
+      const id = node.attributes?.id
+      if (!id) return
+
+      const jsxNode = {
+        type: "mdxJsxFlowElement" as const,
+        name: "YouTube",
+        attributes: [
+          { type: "mdxJsxAttribute" as const, name: "id", value: id },
+        ],
+        children: [],
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      parent.children.splice(index, 1, jsxNode)
+    }
+
+    if (node.name === "audio" && type === "soundcloud") {
+      const url = node.attributes?.url
+      if (!url) return
+
+      const jsxNode = {
+        type: "mdxJsxFlowElement" as const,
+        name: "SoundCloud",
+        attributes: [
+          { type: "mdxJsxAttribute" as const, name: "url", value: url },
+        ],
+        children: [],
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      parent.children.splice(index, 1, jsxNode)
+    }
+  })
+}
+
+/** Remark plugin that converts leaf directives into media embed JSX elements */
+export const remarkMedia: Plugin<[], Root> = () => {
+  return tree => {
+    transformMediaDirectives(tree)
+  }
+}

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

@@ -0,0 +1,74 @@
+import type { Root } from "mdast"
+import type { LeafDirective } from "mdast-util-directive"
+import { describe, expect, it } from "vite-plus/test"
+import { transformMediaDirectives } from "./remark-media.ts"
+
+function makeLeafDirective(
+  name: string,
+  attributes: Record<string, string>,
+): LeafDirective {
+  return {
+    type: "leafDirective" as LeafDirective["type"],
+    name,
+    attributes,
+    children: [],
+  }
+}
+
+function makeTree(...children: Root["children"]): Root {
+  return { type: "root", children }
+}
+
+function process(tree: Root) {
+  transformMediaDirectives(tree)
+  return tree
+}
+
+describe("transformMediaDirectives", () => {
+  it("should convert video youtube directive to YouTube JSX element", () => {
+    const tree = process(
+      makeTree(makeLeafDirective("video", { type: "youtube", id: "abc123" })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "YouTube",
+      attributes: [{ type: "mdxJsxAttribute", name: "id", value: "abc123" }],
+    })
+  })
+
+  it("should convert audio soundcloud directive to SoundCloud JSX element", () => {
+    const url = "https://soundcloud.com/artist/track"
+    const tree = process(
+      makeTree(makeLeafDirective("audio", { type: "soundcloud", url })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "SoundCloud",
+      attributes: [{ type: "mdxJsxAttribute", name: "url", value: url }],
+    })
+  })
+
+  it("should skip video directive without type", () => {
+    const tree = process(makeTree(makeLeafDirective("video", { id: "abc123" })))
+    const node = tree.children[0]
+    expect(node).toMatchObject({ type: "leafDirective", name: "video" })
+  })
+
+  it("should skip audio directive without url", () => {
+    const tree = process(
+      makeTree(makeLeafDirective("audio", { type: "soundcloud" })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({ type: "leafDirective", name: "audio" })
+  })
+
+  it("should ignore unrelated leaf directives", () => {
+    const tree = process(
+      makeTree(makeLeafDirective("include", { file: "test.md" })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({ type: "leafDirective", name: "include" })
+  })
+})

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

@@ -0,0 +1,23 @@
+import type { Root } from "mdast"
+import type { Plugin } from "unified"
+
+/** Remark plugin that converts mermaid code blocks into Mermaid components */
+export const remarkMermaid: Plugin<[], Root> = () => {
+  return tree => {
+    const children = tree.children
+    for (let i = 0; i < children.length; i++) {
+      const node = children[i]
+      if (node?.type !== "code" || node.lang !== "mermaid") continue
+
+      const jsxNode = {
+        type: "mdxJsxFlowElement" as const,
+        name: "Mermaid",
+        attributes: [],
+        children: [{ type: "text" as const, value: node.value }],
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      children[i] = jsxNode
+    }
+  }
+}

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

@@ -0,0 +1,52 @@
+import type { Root } from "mdast"
+import type { Plugin } from "unified"
+import convert from "npm-to-yarn"
+
+type Manager = "npm" | "pnpm" | "yarn" | "bun"
+
+const managers: Manager[] = ["npm", "pnpm", "yarn", "bun"]
+
+interface MdxJsxAttribute {
+  type: "mdxJsxAttribute"
+  name: string
+  value: string
+}
+
+interface MdxJsxFlowElement {
+  type: "mdxJsxFlowElement"
+  name: string
+  attributes: MdxJsxAttribute[]
+  children: []
+}
+
+// @ts-expect-error tsgo does not resolve npm-to-yarn default export correctly
+const convertCommand: (s: string, to: string) => string = convert
+
+/** Remark plugin that converts npm code blocks into PackageTabs components */
+export const remarkNpm: Plugin<[], Root> = () => {
+  return tree => {
+    const children = tree.children
+    for (let i = 0; i < children.length; i++) {
+      const node = children[i]
+      if (node?.type !== "code") continue
+      if (node.lang !== "npm" && node.lang !== "package-install") continue
+
+      const command = node.value.trim()
+      const attributes: MdxJsxAttribute[] = managers.map(pm => ({
+        type: "mdxJsxAttribute" as const,
+        name: pm,
+        value: convertCommand(command, pm),
+      }))
+
+      const jsxNode: MdxJsxFlowElement = {
+        type: "mdxJsxFlowElement",
+        name: "PackageTabs",
+        attributes,
+        children: [],
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      children[i] = jsxNode
+    }
+  }
+}

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

@@ -0,0 +1,36 @@
+import type { Heading, Root } from "mdast"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+const STEP_PATTERN = /\s*\[step\]\s*$/
+
+/** Walk a mdast tree, strip `[step]` suffixes from headings, and add a `data-step` attribute */
+export function transformStepHeadings(tree: Root) {
+  let stepNumber = 0
+
+  visit(tree, "heading", (node: Heading) => {
+    const lastChild = node.children[node.children.length - 1]
+    if (!lastChild || lastChild.type !== "text") return
+    if (!STEP_PATTERN.test(lastChild.value)) return
+
+    stepNumber += 1
+    lastChild.value = lastChild.value.replace(STEP_PATTERN, "")
+
+    if (lastChild.value === "" && node.children.length > 1) {
+      node.children.pop()
+    }
+
+    node.data = node.data ?? {}
+    node.data.hProperties = {
+      ...node.data.hProperties,
+      "data-step": stepNumber,
+    }
+  })
+}
+
+/** Remark plugin that converts `[step]` heading suffixes into numbered step markers */
+export const remarkSteps: Plugin<[], Root> = () => {
+  return tree => {
+    transformStepHeadings(tree)
+  }
+}