feat: introduce unwrap feature in parser (#275)

farnabaz · web-flow · commit 060dfa955c7d · 2026-07-28T17:01:54.000+02:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -479,6 +479,7 @@ describe('functionUnderTest', () => {
 const result = await parse(markdownContent, {
   autoUnwrap: true,   // Remove <p> wrappers from single-paragraph containers
   autoClose: true,    // Auto-close incomplete syntax
+  unwrap: 'p',        // Strip top-level wrapper tags (MDC unwrap); merges paragraphs
 })
 
 result.nodes       // ComarkNode[]
diff --git a/docs/content/3.rendering/3.vue.md b/docs/content/3.rendering/3.vue.md
@@ -97,6 +97,7 @@ Pass markdown content via the default slot or the `markdown` prop:
 | `markdown` | `string` | `undefined` | Alternative to default slot |
 | [`options`](#code-comark-props-code-options) | `ParseOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
 | [`plugins`](#code-comark-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
+| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, e.g. `"ul li"` |
 | [`components`](#code-comark-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
 | [`componentsManifest`](#code-comark-props-code-componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
 | [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
diff --git a/docs/content/3.rendering/4.nuxt.md b/docs/content/3.rendering/4.nuxt.md
@@ -99,6 +99,7 @@ Pass markdown via the default slot or the `markdown` prop:
 | `markdown` | `string` | `undefined` | Alternative to default slot |
 | [`options`](#code-comark-props-code-options) | `ParseOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
 | [`plugins`](#code-comark-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
+| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, e.g. `"ul li"` |
 | [`components`](#code-comark-props-code-components) | `Record<string, Component>` | `{}` | Custom Vue component mappings |
 | [`componentsManifest`](#code-comark-props-code-componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
 | [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
diff --git a/docs/content/3.rendering/5.react.md b/docs/content/3.rendering/5.react.md
@@ -86,6 +86,7 @@ Pass markdown content via `children` or the `markdown` prop:
 | `markdown` | `string` | `''` | Alternative to children |
 | [`options`](#code-comark-props-code-options) | `ParseOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
 | [`plugins`](#code-comark-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
+| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, e.g. `"ul li"` |
 | [`components`](#code-comark-props-code-components) | `Record<string, ComponentType>` | `{}` | Custom React component mappings |
 | [`componentsManifest`](#code-comark-props-code-componentsmanifest) | `(name: string) => Promise<Component>` | `undefined` | Dynamic component resolver |
 | [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
diff --git a/docs/content/3.rendering/6.svelte.md b/docs/content/3.rendering/6.svelte.md
@@ -71,6 +71,7 @@ Pass markdown content via the `markdown` prop:
 | `markdown` | `string` | `''` | Markdown content to parse and render |
 | [`options`](#code-comark-props-code-options) | `ParseOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
 | [`plugins`](#code-comark-props-code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
+| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, e.g. `"ul li"` |
 | [`components`](#code-comark-props-code-components) | `Record<string, Component>` | `{}` | Custom Svelte component mappings |
 | [`componentsManifest`](#code-comark-props-code-componentsmanifest) | `ComponentManifest` | `undefined` | Dynamic component resolver |
 | [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
diff --git a/docs/content/3.rendering/7.angular.md b/docs/content/3.rendering/7.angular.md
@@ -81,6 +81,7 @@ This is **markdown** with Comark components.
 | `markdown` | `string` | `''` | Markdown content to parse and render |
 | [`options`](#code-options) | `ParseOptions` | `{}` | Parser options (autoUnwrap, autoClose, etc.) |
 | [`plugins`](#code-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins |
+| `unwrap` | `boolean \| string \| string[]` | `false` | Strip wrapper tags (MDC `unwrap`) — `true` unwraps `<p>`; a comma/space-separated string or array peels tags sequentially, e.g. `"ul li"` |
 | [`components`](#code-components) | `Record<string, Type<any>>` | `{}` | Custom Angular component mappings |
 | [`streaming`](#streaming) | `boolean` | `false` | Enable streaming mode |
 | `summary` | `boolean` | `false` | Only render content before `<!-- more -->` |
diff --git a/docs/content/5.api/1.parse.md b/docs/content/5.api/1.parse.md
@@ -363,9 +363,42 @@ Both `parse()` and `createParse()` accept the same `ParseOptions`:
 |--------|------|---------|-------------|
 | `autoUnwrap` | `boolean` | `true` | Remove unnecessary `<p>` wrappers from single-element containers |
 | `autoClose` | `boolean` | `true` | Auto-close incomplete markdown syntax |
+| `unwrap` | `boolean \| string \| string[]` | `false` | Remove wrapper tags from the tree, hoisting their children (MDC `unwrap` behaviour). `true` unwraps `p`; a comma/whitespace-separated string or array unwraps the listed tags; `'*'` matches any tag. Tags apply sequentially (each descends one level), and adjacent text is merged into a single string. |
 | `html` | `boolean` | `true` | Parse embedded HTML tags into AST nodes |
 | `linkify` | `boolean` | `true` | Auto-convert URL-like text into links. Set `false` to disable |
 | `headingIds` | `boolean` | `true` | Auto-generate `id` attributes for `h1`–`h6` headings. Set `false` to disable |
 | `plugins` | `ComarkPlugin[]` | `[]` | Array of plugins to apply |
 
+### Inline rendering
+
+Use `unwrap: 'p'` (or just `unwrap: true`) to render markdown without the
+wrapping `<p>`, which is handy for buttons, badges, and other inline hosts.
+Adjacent text is merged into a single string, matching MDC's `unwrap`:
+
+```ts
+await parse('Hello **world**', { unwrap: 'p' })
+// nodes: ['Hello ', ['strong', {}, 'world']]
+
+await parse('a\n\nb', { unwrap: true })
+// nodes: ['ab']   (paragraphs merged, no separator)
+```
+
+Tags are applied **sequentially**, each descending one level into the result of
+the previous one — so a space-separated (or comma-separated) list peels nested
+wrappers. `'*'` matches any tag:
+
+```ts
+// Unwrap the <ul>, then the <li> inside it
+await parse('- Buy milk', { unwrap: 'ul li' })
+// nodes: ['Buy milk']
+```
+
+On the framework components this is exposed as an `unwrap` shorthand prop:
+
+```vue
+<UButton><Comark :markdown="text" unwrap /></UButton>
+<UButton><Comark :markdown="text" unwrap="ul li" /></UButton>
+<UButton><Comark :markdown="text" :options="{ unwrap: 'p' }" /></UButton>
+```
+
 ---
diff --git a/docs/content/7.kb/2.migration-from-mdc.md b/docs/content/7.kb/2.migration-from-mdc.md
@@ -381,7 +381,7 @@ Props that changed:
 | `data` | — | `tree.frontmatter` contains frontmatter, not a separate prop |
 | `tag` | — | Wrapper is always `<div class="comark-content">` |
 | `prose` | — | `Prose*` component resolution is automatic |
-| `unwrap` | — | Use `autoUnwrap` in parse options instead |
+| `unwrap` | `unwrap` prop / parse option | `<Comark unwrap />` or `:options="{ unwrap: 'p' }"` — see [inline rendering](/api/parse#inline-rendering) |
 | `class` | — | Style the wrapper via CSS |
 | `components` | `components` | Same purpose, same shape |
 | — | `componentsManifest` | New: dynamic async component resolver |
diff --git a/packages/comark-angular/package.json b/packages/comark-angular/package.json
@@ -45,7 +45,7 @@
     "release": "release-it"
   },
   "dependencies": {
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "@angular/common": "^22.0.6",
diff --git a/packages/comark-angular/src/components/comark.component.ts b/packages/comark-angular/src/components/comark.component.ts
@@ -47,6 +47,13 @@ export class ComarkComponent implements OnChanges {
   /** Additional plugins to use */
   @Input() plugins: ParseOptions['plugins'] = []
 
+  /**
+   * Strip wrapper tags from the top level of the tree — shorthand for
+   * `options.unwrap`. `true` unwraps `<p>`; a space-separated string or array
+   * unwraps the listed tags.
+   */
+  @Input() unwrap: boolean | string | string[] = false
+
   /** Custom component mappings for element tags */
   @Input() components: Record<string, Type<any>> = {}
 
@@ -69,10 +76,21 @@ export class ComarkComponent implements OnChanges {
   constructor(private cdr: ChangeDetectorRef) {}
 
   ngOnChanges(changes: SimpleChanges): void {
-    if (changes['options'] || changes['plugins']) {
-      this.serializedParse = createSerializedParse({ ...this.options, plugins: this.plugins })
+    if (changes['options'] || changes['plugins'] || changes['unwrap']) {
+      this.serializedParse = createSerializedParse({
+        ...this.options,
+        ...(this.unwrap ? { unwrap: this.unwrap } : {}),
+        plugins: this.plugins,
+      })
     }
-    if (changes['markdown'] || changes['options'] || changes['plugins'] || changes['streaming'] || changes['summary']) {
+    if (
+      changes['markdown'] ||
+      changes['options'] ||
+      changes['plugins'] ||
+      changes['unwrap'] ||
+      changes['streaming'] ||
+      changes['summary']
+    ) {
       this.parseMarkdown()
     }
   }
diff --git a/packages/comark-ansi/package.json b/packages/comark-ansi/package.json
@@ -48,7 +48,7 @@
     "release": "release-it"
   },
   "dependencies": {
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "vitest": "catalog:"
diff --git a/packages/comark-html/package.json b/packages/comark-html/package.json
@@ -47,7 +47,7 @@
     "release": "release-it"
   },
   "dependencies": {
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "beautiful-mermaid": "catalog:",
diff --git a/packages/comark-nuxt/package.json b/packages/comark-nuxt/package.json
@@ -51,7 +51,7 @@
   "dependencies": {
     "@comark/vue": "catalog:",
     "@nuxt/kit": "catalog:",
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "@vue/server-renderer": "catalog:",
diff --git a/packages/comark-react/package.json b/packages/comark-react/package.json
@@ -50,7 +50,7 @@
     "release": "release-it"
   },
   "dependencies": {
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "@types/react": "catalog:",
diff --git a/packages/comark-react/src/components/Comark.tsx b/packages/comark-react/src/components/Comark.tsx
@@ -38,6 +38,14 @@ export interface ComarkProps {
    */
   componentsManifest?: (name: string) => Promise<{ default: React.ComponentType<any> }>
 
+  /**
+   * Strip wrapper tags from the top level of the tree — shorthand for
+   * `options.unwrap`. `true` unwraps `<p>` (single-line rendering); a
+   * space-separated string or array unwraps the listed tags. Useful for inline
+   * usage like `<button><Comark markdown={text} unwrap /></button>`.
+   */
+  unwrap?: boolean | string | string[]
+
   /**
    * Enable streaming mode — delegates to ComarkClient for client-side re-rendering
    * when the markdown prop changes. Use this for LLM streaming output.
@@ -98,6 +106,7 @@ export async function Comark({
   markdown = '',
   options = {},
   plugins = [],
+  unwrap = false,
   components: customComponents = {},
   componentsManifest,
   streaming = false,
@@ -106,12 +115,15 @@ export async function Comark({
   className,
 }: ComarkProps) {
   const source = children ? String(children) : 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
 
   if (streaming) {
     return (
       <ComarkClient
         markdown={source}
-        options={options}
+        options={parseOptions}
         plugins={plugins}
         components={customComponents}
         componentsManifest={componentsManifest}
@@ -123,7 +135,7 @@ export async function Comark({
     )
   }
 
-  const parsed = await parse(source, { ...options, plugins })
+  const parsed = await parse(source, { ...parseOptions, plugins })
 
   return (
     <ComarkRenderer
diff --git a/packages/comark-react/test/unwrap.test.tsx b/packages/comark-react/test/unwrap.test.tsx
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { Comark } from '../src/components/Comark'
+
+/**
+ * Tests for the `unwrap` shorthand prop / `options.unwrap` on the high-level
+ * Comark component — the MDC `unwrap="p"` migration path for inline rendering.
+ *
+ * `Comark` is an async server component, so we await it to obtain the element
+ * before handing it to `renderToString`.
+ */
+async function renderComark(props: Record<string, unknown>) {
+  const element = await Comark(props as any)
+  return renderToString(element as React.ReactElement)
+}
+
+describe('Comark unwrap', () => {
+  it('wraps single-line content in a paragraph by default', async () => {
+    const html = await renderComark({ markdown: 'Hello **world**' })
+    expect(html).toContain('<p>')
+    expect(html).toContain('<strong>world</strong>')
+  })
+
+  it('drops the paragraph wrapper with the `unwrap` prop', async () => {
+    const html = await renderComark({ markdown: 'Hello **world**', unwrap: true })
+    expect(html).not.toContain('<p>')
+    expect(html).toContain('<strong>world</strong>')
+  })
+
+  it('accepts a tag string on the `unwrap` prop', async () => {
+    const html = await renderComark({ markdown: 'Hello **world**', unwrap: 'p' })
+    expect(html).not.toContain('<p>')
+    expect(html).toContain('<strong>world</strong>')
+  })
+
+  it('merges paragraphs into a single string without a separator', async () => {
+    const html = await renderComark({ markdown: 'a\n\nb', unwrap: 'p' })
+    expect(html).not.toContain('<p>')
+    expect(html).not.toContain('<br')
+    // Adjacent paragraphs collapse into one text node (MDC behaviour), so
+    // there's no comment marker between them.
+    expect(html).not.toContain('a<!-- -->b')
+    expect(html).toContain('ab')
+  })
+
+  it('supports `options.unwrap` equivalently', async () => {
+    const html = await renderComark({ markdown: 'Hello **world**', options: { unwrap: 'p' } })
+    expect(html).not.toContain('<p>')
+    expect(html).toContain('<strong>world</strong>')
+  })
+})
diff --git a/packages/comark-svelte/package.json b/packages/comark-svelte/package.json
@@ -64,7 +64,7 @@
     "release": "release-it"
   },
   "dependencies": {
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "@sveltejs/package": "catalog:",
diff --git a/packages/comark-svelte/src/async/ComarkAsync.svelte b/packages/comark-svelte/src/async/ComarkAsync.svelte
@@ -37,6 +37,7 @@ and wrap this component in a `<svelte:boundary>` for pending/error states.
     markdown = '',
     options = {},
     plugins = [],
+    unwrap = false,
     components = {},
     componentsManifest,
     streaming = false,
@@ -47,6 +48,7 @@ and wrap this component in a `<svelte:boundary>` for pending/error states.
     markdown?: string
     options?: Record<string, any>
     plugins?: ComarkPlugin[]
+    unwrap?: boolean | string | string[]
     components?: Record<string, any>
     componentsManifest?: ComponentManifest
     streaming?: boolean
@@ -60,7 +62,7 @@ and wrap this component in a `<svelte:boundary>` for pending/error states.
     // `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, plugins: [...plugins] }),
+    await parse(content, { ...options, ...(unwrap ? { unwrap } : {}), plugins: [...plugins] }),
   )
 </script>
 
diff --git a/packages/comark-svelte/src/components/Comark.svelte b/packages/comark-svelte/src/components/Comark.svelte
@@ -32,6 +32,7 @@ This is an alert component
     markdown = '',
     options = {},
     plugins = [],
+    unwrap = false,
     components = {},
     componentsManifest,
     streaming = false,
@@ -42,6 +43,7 @@ This is an alert component
     markdown?: string
     options?: Record<string, any>
     plugins?: ComarkPlugin[]
+    unwrap?: boolean | string | string[]
     components?: Record<string, any>
     componentsManifest?: ComponentManifest
     streaming?: boolean
@@ -61,7 +63,7 @@ This is an alert component
     // `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
-    parse(content, { ...options, plugins: [...plugins] }).then((result) => {
+    parse(content, { ...options, ...(unwrap ? { unwrap } : {}), plugins: [...plugins] }).then((result) => {
       if (currentVersion > appliedVersion) {
         appliedVersion = currentVersion
         parsed = result
diff --git a/packages/comark-svelte/src/types.ts b/packages/comark-svelte/src/types.ts
@@ -32,6 +32,12 @@ export interface ComarkProps {
   markdown?: string
   options?: Exclude<ParseOptions, 'plugins'>
   plugins?: ComarkPlugin[]
+  /**
+   * Strip wrapper tags from the top level of the tree — shorthand for
+   * `options.unwrap`. `true` unwraps `<p>`; a space-separated string or array
+   * unwraps the listed tags.
+   */
+  unwrap?: boolean | string | string[]
   components?: Record<string, any>
   componentsManifest?: ComponentManifest
   streaming?: boolean
diff --git a/packages/comark-vue/package.json b/packages/comark-vue/package.json
@@ -49,7 +49,7 @@
     "release": "release-it"
   },
   "dependencies": {
-    "comark": "catalog:"
+    "comark": "workspace:*"
   },
   "devDependencies": {
     "@vue/compiler-core": "catalog:",
diff --git a/packages/comark-vue/src/components/Comark.ts b/packages/comark-vue/src/components/Comark.ts
diff --git a/packages/comark-vue/src/index.ts b/packages/comark-vue/src/index.ts
diff --git a/packages/comark-vue/test/unwrap.test.ts b/packages/comark-vue/test/unwrap.test.ts
diff --git a/packages/comark/src/internal/parse/unwrap.ts b/packages/comark/src/internal/parse/unwrap.ts
diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts
diff --git a/packages/comark/src/types.ts b/packages/comark/src/types.ts
diff --git a/packages/comark/test/unwrap.test.ts b/packages/comark/test/unwrap.test.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/bundle.test.ts b/test/bundle.test.ts
