feat: allow passing MarkdownTree to <Markdown> component

Author: farnabaz

packages/comark-angular/src/components/markdown.component.ts

@@ -9,6 +9,7 @@ import {
 } from '@angular/core'
 import { createSerializedParse } from 'comark'
 import type { ParseOptions, MarkdownTree } from 'comark'
+import { isMarkdownTree } from 'comark/utils'
 import { MarkdownParsed } from './markdown-parsed.component.ts'
 import { warnDeprecated } from '../internal/deprecation.ts'
 
@@ -39,8 +40,8 @@ import { warnDeprecated } from '../internal/deprecation.ts'
   `,
 })
 export class Markdown implements OnChanges {
-  /** The markdown content to parse and render */
-  @Input() value?: string
+  /** The markdown content to parse and render, or a pre-parsed MarkdownTree */
+  @Input() value?: string | MarkdownTree
 
   /**
    * The markdown content to parse and render
@@ -107,7 +108,14 @@ export class Markdown implements OnChanges {
   }
 
   private parseMarkdown(): void {
-    let source = this.value ?? this.markdown ?? ''
+    // Pre-parsed tree — skip parse and render directly
+    if (isMarkdownTree(this.value)) {
+      this.tree = this.value
+      this.cdr.markForCheck()
+      return
+    }
+
+    let source = (this.value as string | undefined) ?? this.markdown ?? ''
     if (this.summary) {
       source = source.split('<!-- more -->')[0] || ''
     }

packages/comark-angular/test/markdown-tree-value.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest'
+import { parse } from 'comark'
+import { isMarkdownTree } from 'comark/utils'
+import type { MarkdownTree } from 'comark'
+import { Markdown } from '../src/components/markdown.component.ts'
+
+/**
+ * Angular's high-level Markdown component accepts a string or a pre-parsed
+ * MarkdownTree on `value`. When a tree is passed, parse is skipped and the
+ * tree is assigned for MarkdownParsed to render.
+ */
+function createMarkdown(): Markdown {
+  const cdr = { markForCheck: vi.fn() }
+  return new Markdown(cdr as any)
+}
+
+describe('Markdown value as MarkdownTree', () => {
+  it('assigns a pre-parsed tree without calling parse', async () => {
+    const tree = await parse('# Hello **World**')
+    const component = createMarkdown()
+
+    component.value = tree
+    component.ngOnChanges({
+      value: {
+        currentValue: tree,
+        previousValue: undefined,
+        firstChange: true,
+        isFirstChange: () => true,
+      },
+    })
+
+    expect(isMarkdownTree(component.value)).toBe(true)
+    expect(component.tree).toBe(tree)
+    expect(component.tree!.nodes[0]?.[0]).toBe('h1')
+  })
+
+  it('still parses markdown strings', async () => {
+    const component = createMarkdown()
+    component.value = 'Hello **world**'
+    component.ngOnChanges({
+      value: {
+        currentValue: 'Hello **world**',
+        previousValue: undefined,
+        firstChange: true,
+        isFirstChange: () => true,
+      },
+    })
+
+    // Wait for async parse
+    await vi.waitFor(() => {
+      expect(component.tree).not.toBeNull()
+    })
+
+    expect(component.tree!.nodes[0]?.[0]).toBe('p')
+  })
+
+  it('accepts an empty tree', () => {
+    const empty: MarkdownTree = { nodes: [], frontmatter: {}, meta: {} }
+    const component = createMarkdown()
+    component.value = empty
+    component.ngOnChanges({
+      value: {
+        currentValue: empty,
+        previousValue: undefined,
+        firstChange: true,
+        isFirstChange: () => true,
+      },
+    })
+
+    expect(component.tree).toBe(empty)
+    expect(component.tree!.nodes).toEqual([])
+  })
+})

packages/comark-react/src/components/Markdown.tsx

@@ -1,6 +1,7 @@
 import React from 'react'
 import { parse } from 'comark'
-import type { ParseOptions } from 'comark'
+import type { MarkdownTree, ParseOptions } from 'comark'
+import { isMarkdownTree } from 'comark/utils'
 import { MarkdownParsed } from './MarkdownParsed.tsx'
 import { MarkdownClient } from './MarkdownClient.tsx'
 import { warnDeprecated } from '../internal/deprecation.ts'
@@ -12,9 +13,9 @@ export interface MarkdownProps {
   children?: React.ReactNode
 
   /**
-   * The markdown content to parse and render
+   * The markdown content to parse and render, or a pre-parsed MarkdownTree
    */
-  value?: string
+  value?: string | MarkdownTree
 
   /**
    * The markdown content to parse and render
@@ -125,7 +126,23 @@ export async function Markdown({
   if (markdown !== undefined && value === undefined) {
     warnDeprecated('markdown (prop)', 'value')
   }
-  const source = children ? String(children) : (value ?? markdown ?? '')
+
+  // Pre-parsed tree — skip parse and render directly
+  if (isMarkdownTree(value)) {
+    return (
+      <MarkdownParsed
+        value={value}
+        components={customComponents}
+        componentsManifest={componentsManifest}
+        streaming={streaming}
+        className={className}
+        caret={caret}
+        data={data}
+      />
+    )
+  }
+
+  const source = children ? String(children) : ((value as string | undefined) ?? markdown ?? '')
   // `unwrap` prop is a shorthand for the `unwrap` parse option; an explicit
   // `options.unwrap` still wins when the prop is left at its default.
   const parseOptions = unwrap ? { ...options, unwrap } : options

packages/comark-react/src/components/MarkdownClient.tsx

@@ -3,6 +3,7 @@
 import { use, useDeferredValue, useMemo, Suspense } from 'react'
 import { parse } from 'comark'
 import type { MarkdownTree } from 'comark'
+import { isMarkdownTree } from 'comark/utils'
 import { MarkdownLive } from './MarkdownLive.tsx'
 import type { MarkdownProps } from './Markdown'
 
@@ -35,11 +36,19 @@ function MarkdownContent({
 }
 
 export function MarkdownClient({ children, value, markdown, options = {}, plugins = [], ...rest }: MarkdownProps) {
-  const content = children ? String(children) : (value ?? markdown ?? '')
+  const content = isMarkdownTree(value)
+    ? value
+    : children
+      ? String(children)
+      : ((value as string | undefined) ?? markdown ?? '')
 
   // Re-creates the promise only when content changes.
   // Note: options/plugins should be stable references (defined outside render or memoized).
-  const parsePromise = useMemo(() => parse(content, { ...options, plugins }), [content])
+  // Pre-parsed trees resolve immediately without calling parse().
+  const parsePromise = useMemo(
+    () => (isMarkdownTree(content) ? Promise.resolve(content) : parse(content, { ...options, plugins })),
+    [content]
+  )
 
   // Keep showing the previous parsed result while a new parse is pending —
   // prevents blank flashes during rapid streaming updates.

packages/comark-react/test/markdown-tree-value.test.tsx

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { parse } from 'comark'
+import { Markdown } from '../src/components/Markdown'
+import { MarkdownParsed } from '../src/components/MarkdownParsed'
+
+/**
+ * Markdown accepts either a markdown string or a pre-parsed MarkdownTree on
+ * `value`. When a tree is passed it should render via MarkdownParsed without
+ * re-parsing.
+ */
+async function renderMarkdownComponent(props: Record<string, unknown>) {
+  const element = await Markdown(props as any)
+  return renderToString(element as React.ReactElement)
+}
+
+function renderMarkdownParsedComponent(props: Record<string, unknown>) {
+  return renderToString(<MarkdownParsed {...(props as any)} />)
+}
+
+describe('Markdown value as MarkdownTree', () => {
+  it('renders a pre-parsed tree the same as MarkdownParsed', async () => {
+    const tree = await parse('# Hello **World**')
+    const fromMarkdown = await renderMarkdownComponent({ value: tree })
+    const fromParsed = renderMarkdownParsedComponent({ value: tree })
+
+    expect(fromMarkdown).toContain('<h1')
+    expect(fromMarkdown).toContain('Hello <strong>World</strong>')
+    expect(fromMarkdown).toBe(fromParsed)
+  })
+
+  it('still renders markdown strings', async () => {
+    const html = await renderMarkdownComponent({ value: 'Hello **world**' })
+    expect(html).toContain('<p>')
+    expect(html).toContain('<strong>world</strong>')
+  })
+
+  it('renders an empty tree without crashing', async () => {
+    const html = await renderMarkdownComponent({
+      value: { nodes: [], frontmatter: {}, meta: {} },
+    })
+    expect(html).toContain('comark-content')
+  })
+})

packages/comark-svelte/src/async/MarkdownAsync.svelte

@@ -28,8 +28,9 @@ and wrap this component in a `<svelte:boundary>` for pending/error states.
 ```
 -->
 <script lang="ts">
-  import type { ComarkPlugin, ComponentManifest } from 'comark'
+  import type { MarkdownTree, ComarkPlugin, ComponentManifest } from 'comark'
   import { parse } from 'comark'
+  import { isMarkdownTree } from 'comark/utils'
   import MarkdownParsed from '../components/MarkdownParsed.svelte'
   import ResolveAsync from './ResolveAsync.svelte'
   import { warnDeprecated } from '../internal/deprecation.js'
@@ -47,7 +48,7 @@ and wrap this component in a `<svelte:boundary>` for pending/error states.
     data,
     class: className = '',
   }: {
-    value?: string
+    value?: string | MarkdownTree
     /** @deprecated Use `value` instead */
     markdown?: string
     options?: Record<string, any>
@@ -66,12 +67,14 @@ and wrap this component in a `<svelte:boundary>` for pending/error states.
     warnDeprecated('markdown (prop)', 'value')
   }
 
-  let content = $derived((value ?? markdown ?? '').trim())
+  let content = $derived(typeof value === 'string' ? value.trim() : (markdown ?? '').trim())
   let parsed = $derived(
-    // `parse` directly mutates `plugins` which creates an infinite effect loop
-    // so we copy it before passing it in so it gets a regular JS array and we get to still
-    // track dependencies from an external perspective
-    await parse(content, { ...options, ...(unwrap ? { unwrap } : {}), plugins: [...plugins] }),
+    isMarkdownTree(value)
+      ? value
+      : // `parse` directly mutates `plugins` which creates an infinite effect loop
+        // so we copy it before passing it in so it gets a regular JS array and we get to still
+        // track dependencies from an external perspective
+        await parse(content, { ...options, ...(unwrap ? { unwrap } : {}), plugins: [...plugins] }),
   )
 </script>
 

packages/comark-svelte/src/components/Markdown.svelte

@@ -25,7 +25,8 @@ This is an alert component
 -->
 <script lang="ts">
   import type { MarkdownTree, ComarkPlugin, ComponentManifest } from 'comark'
-    import { parse } from 'comark'
+  import { parse } from 'comark'
+  import { isMarkdownTree } from 'comark/utils'
   import MarkdownParsed from './MarkdownParsed.svelte'
   import { warnDeprecated } from '../internal/deprecation.js'
 
@@ -42,7 +43,7 @@ This is an alert component
     data,
     class: className = '',
   }: {
-    value?: string
+    value?: string | MarkdownTree
     /** @deprecated Use `value` instead */
     markdown?: string
     options?: Record<string, any>
@@ -63,11 +64,12 @@ This is an alert component
 
   let parsed: MarkdownTree | null = $state(null)
 
-  let content = $derived((value ?? markdown ?? '').trim())
+  let content = $derived(typeof value === 'string' ? value.trim() : (markdown ?? '').trim())
 
   let requestVersion = 0
   let appliedVersion = 0
   $effect(() => {
+    if (isMarkdownTree(value)) return
     const currentVersion = ++requestVersion
     // `parse` directly mutates `plugins` which creates an infinite effect loop
     // so we copy it before passing it in so it gets a regular JS array and we get to still
@@ -81,7 +83,17 @@ This is an alert component
   })
 </script>
 
-{#if parsed}
+{#if isMarkdownTree(value)}
+  <MarkdownParsed
+    {value}
+    {components}
+    {componentsManifest}
+    {streaming}
+    {caret}
+    {data}
+    class={className}
+  />
+{:else if parsed}
   <MarkdownParsed
     value={parsed}
     {components}

packages/comark-svelte/src/types.ts

@@ -32,8 +32,8 @@ export interface MarkdownParsedProps {
 }
 
 export interface MarkdownProps {
-  /** The markdown content to parse and render */
-  value?: string
+  /** The markdown content to parse and render, or a pre-parsed MarkdownTree */
+  value?: string | MarkdownTree
   /** @deprecated Use `value` instead */
   markdown?: string
   options?: Exclude<ParseOptions, 'plugins'>

packages/comark-svelte/test/markdown-tree-value.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { render } from 'svelte/server'
+import { parse } from 'comark'
+import Markdown from '../src/components/Markdown.svelte'
+import MarkdownParsed from '../src/components/MarkdownParsed.svelte'
+import MarkdownAsync from '../src/async/MarkdownAsync.svelte'
+
+/** Strip Svelte SSR hydration comments from rendered HTML */
+function html(body: string): string {
+  return body.replace(/<!--[[\]\-\d!]*-->/g, '').replace(/<!---->/g, '')
+}
+
+describe('Markdown value as MarkdownTree', () => {
+  it('renders a pre-parsed tree the same as MarkdownParsed', async () => {
+    const tree = await parse('# Hello **World**')
+    const fromMarkdown = html(render(Markdown, { props: { value: tree } }).body)
+    const fromParsed = html(render(MarkdownParsed, { props: { value: tree } }).body)
+
+    expect(fromMarkdown).toContain('<h1')
+    expect(fromMarkdown).toContain('Hello <strong>World</strong>')
+    expect(fromMarkdown).toBe(fromParsed)
+  })
+
+  it('still renders markdown strings after parse settles', async () => {
+    // Server render of Markdown only emits once parse has completed in $effect —
+    // string path is empty on first SSR tick. MarkdownAsync covers the string path.
+    const { body } = await render(MarkdownAsync, {
+      props: { value: 'Hello **world**' },
+    })
+    const output = html(body)
+    expect(output).toContain('<p>')
+    expect(output).toContain('<strong>world</strong>')
+  })
+
+  it('renders an empty tree without crashing', () => {
+    const { body } = render(Markdown, {
+      props: { value: { nodes: [], frontmatter: {}, meta: {} } },
+    })
+    expect(html(body)).toBe('<div class="comark-content "></div>')
+  })
+})
+
+describe('MarkdownAsync value as MarkdownTree', () => {
+  it('renders a pre-parsed tree without parsing', async () => {
+    const tree = await parse('# Hello **World**')
+    const { body } = await render(MarkdownAsync, { props: { value: tree } })
+    const output = html(body)
+    expect(output).toContain('<h1')
+    expect(output).toContain('Hello <strong>World</strong>')
+  })
+
+  it('renders a tree the same as MarkdownParsed', async () => {
+    const tree = await parse('A paragraph with **bold**')
+    const fromAsync = html((await render(MarkdownAsync, { props: { value: tree } })).body)
+    const fromParsed = html(render(MarkdownParsed, { props: { value: tree } }).body)
+    expect(fromAsync).toBe(fromParsed)
+  })
+})