feat: auto unwrap single child paragraphs

Author: farnabaz

src/index.ts

@@ -1,8 +1,10 @@
-import type { MDCRoot } from './types/tree'
+import type { MDCRoot, MDCElement } from './types/tree'
+import type { ParseOptions } from './types'
 import MarkdownIt from 'markdown-it'
 import pluginMdc from 'markdown-it-mdc'
 import { parseFrontMatter } from 'remark-mdc'
 import { convertMarkdownItTokensToMDC } from './utils/parse'
+import { applyAutoUnwrap } from './utils/auto-unwrap'
 import { generateToc } from './utils/table-of-contents'
 
 export interface ParseResult {
@@ -15,13 +17,18 @@ export interface ParseResult {
 // Re-export auto-close utilities
 export { autoCloseMarkdown, detectUnclosedSyntax } from './auto-close'
 
+// Re-export parse utilities
+export { applyAutoUnwrap } from './utils/auto-unwrap'
+
 // Re-export types
-export type { MDCNode, MDCRoot } from './types/tree'
+export type { MDCNode, MDCRoot, MDCElement, MDCText, MDCComment } from './types/tree'
+export type { ParseOptions } from './types'
 
 /**
  * Parse MDC content from a string
  *
  * @param source - The markdown/MDC content as a string
+ * @param options - Parser options
  * @returns ParseResult - Object containing body, excerpt, data, and toc
  *
  * @example
@@ -45,9 +52,13 @@ export type { MDCNode, MDCRoot } from './types/tree'
  * console.log(result.body)    // MDC AST
  * console.log(result.data)    // { title: 'Hello World' }
  * console.log(result.toc)     // Table of contents
+ *
+ * // Disable auto-unwrap
+ * const result2 = parse(content, { autoUnwrap: false })
  * ```
  */
-export function parse(source: string): ParseResult {
+export function parse(source: string, options: ParseOptions = {}): ParseResult {
+  const { autoUnwrap = true } = options
   const { content, data } = parseFrontMatter(source)
 
   // Enable tables, GFM features
@@ -64,7 +75,17 @@ export function parse(source: string): ParseResult {
   const children = convertMarkdownItTokensToMDC(tokens)
 
   // Filter out top-level text nodes
-  const filteredChildren = children.filter(child => child.type !== 'text')
+  let filteredChildren = children.filter(child => child.type !== 'text')
+
+  // Apply auto-unwrap to container components if enabled
+  if (autoUnwrap) {
+    filteredChildren = filteredChildren.map((child) => {
+      if (child.type === 'element') {
+        return applyAutoUnwrap(child as MDCElement)
+      }
+      return child
+    })
+  }
 
   const body: MDCRoot = {
     type: 'root',
@@ -79,7 +100,18 @@ export function parse(source: string): ParseResult {
 
   if (excerptIndex !== -1) {
     const excerptTokens = tokens.slice(0, excerptIndex)
-    const excerptChildren = convertMarkdownItTokensToMDC(excerptTokens, new Set())
+    let excerptChildren = convertMarkdownItTokensToMDC(excerptTokens as any, new Set())
+
+    // Apply auto-unwrap to excerpt as well
+    if (autoUnwrap) {
+      excerptChildren = excerptChildren.map((child) => {
+        if (child.type === 'element') {
+          return applyAutoUnwrap(child as MDCElement)
+        }
+        return child
+      })
+    }
+
     excerpt = {
       type: 'root',
       children: excerptChildren.filter(child => child.type !== 'text'),

src/stream.ts

@@ -1,10 +1,12 @@
 import type { Readable } from 'node:stream'
-import type { MDCRoot } from './types/tree'
+import type { MDCRoot, MDCElement } from './types/tree'
+import type { ParseOptions } from './types'
 import MarkdownIt from 'markdown-it'
 import pluginMdc from 'markdown-it-mdc'
 import { parseFrontMatter } from 'remark-mdc'
 import { autoCloseMarkdown } from './auto-close'
 import { convertMarkdownItTokensToMDC } from './utils/parse'
+import { applyAutoUnwrap } from './utils/auto-unwrap'
 import { generateToc } from './utils/table-of-contents'
 
 export interface ParseResult {
@@ -92,7 +94,8 @@ async function streamToString(stream: Readable | ReadableStream<Uint8Array>): Pr
 /**
  * Internal parse function
  */
-function parseContent(source: string): ParseResult {
+function parseContent(source: string, options: ParseOptions = {}): ParseResult {
+  const { autoUnwrap = true } = options
   const { content, data } = parseFrontMatter(source)
   // Enable tables, GFM features
   const markdownIt = new MarkdownIt({
@@ -107,7 +110,17 @@ function parseContent(source: string): ParseResult {
   const children = convertMarkdownItTokensToMDC(tokens)
 
   // Filter out top-level text nodes
-  const filteredChildren = children.filter(child => child.type !== 'text')
+  let filteredChildren = children.filter(child => child.type !== 'text')
+
+  // Apply auto-unwrap to container components if enabled
+  if (autoUnwrap) {
+    filteredChildren = filteredChildren.map((child) => {
+      if (child.type === 'element') {
+        return applyAutoUnwrap(child as MDCElement)
+      }
+      return child
+    })
+  }
 
   const body: MDCRoot = {
     type: 'root',
@@ -122,7 +135,18 @@ function parseContent(source: string): ParseResult {
 
   if (excerptIndex !== -1) {
     const excerptTokens = tokens.slice(0, excerptIndex)
-    const excerptChildren = convertMarkdownItTokensToMDC(excerptTokens, new Set())
+    let excerptChildren = convertMarkdownItTokensToMDC(excerptTokens as any, new Set())
+
+    // Apply auto-unwrap to excerpt as well
+    if (autoUnwrap) {
+      excerptChildren = excerptChildren.map((child) => {
+        if (child.type === 'element') {
+          return applyAutoUnwrap(child as MDCElement)
+        }
+        return child
+      })
+    }
+
     excerpt = {
       type: 'root',
       children: excerptChildren.filter(child => child.type !== 'text'),
@@ -156,6 +180,7 @@ function parseContent(source: string): ParseResult {
  * Parse MDC content from a Node.js Readable stream or Web ReadableStream
  *
  * @param stream - A Node.js Readable stream or Web ReadableStream containing MDC content
+ * @param options - Parser options
  * @returns Promise resolving to the parsed MDC structure
  *
  * @example
@@ -166,18 +191,22 @@ function parseContent(source: string): ParseResult {
  * const stream = createReadStream('content.md')
  * const result = await parseStream(stream)
  * console.log(result.body)
+ *
+ * // Disable auto-unwrap
+ * const result2 = await parseStream(stream, { autoUnwrap: false })
  * ```
  */
-export async function parseStream(stream: Readable | ReadableStream<Uint8Array>): Promise<ParseResult> {
+export async function parseStream(stream: Readable | ReadableStream<Uint8Array>, options?: ParseOptions): Promise<ParseResult> {
   const content = await streamToString(stream)
-  return parseContent(content)
+  return parseContent(content, options)
 }
 
 /**
  * Parse MDC content incrementally from a stream,
  * yielding results as each chunk is received
  *
  * @param stream - A Node.js Readable stream or Web ReadableStream containing MDC content
+ * @param options - Parser options
  * @yields IncrementalParseResult for each chunk received
  *
  * @example
@@ -191,10 +220,16 @@ export async function parseStream(stream: Readable | ReadableStream<Uint8Array>)
  *   console.log('Current body:', result.body)
  *   console.log('Complete:', result.isComplete)
  * }
+ *
+ * // Disable auto-unwrap
+ * for await (const result of parseStreamIncremental(stream, { autoUnwrap: false })) {
+ *   // ...
+ * }
  * ```
  */
 export async function* parseStreamIncremental(
   stream: Readable | ReadableStream<Uint8Array>,
+  options?: ParseOptions,
 ): AsyncGenerator<IncrementalParseResult, void, unknown> {
   let accumulatedContent = ''
   let frontmatterParsed = false
@@ -230,7 +265,7 @@ export async function* parseStreamIncremental(
       const closedContent = autoCloseMarkdown(accumulatedContent)
 
       // Parse the auto-closed content
-      const result = parseContent(closedContent)
+      const result = parseContent(closedContent, options)
 
       yield {
         chunk: chunkStr,
@@ -242,7 +277,7 @@ export async function* parseStreamIncremental(
     }
 
     // Final parse with complete content (no auto-close needed, content is complete)
-    const finalResult = parseContent(accumulatedContent)
+    const finalResult = parseContent(accumulatedContent, options)
     yield {
       chunk: '',
       body: finalResult.body,
@@ -263,7 +298,7 @@ export async function* parseStreamIncremental(
 
         if (done) {
           // Final parse with complete content
-          const finalResult = parseContent(accumulatedContent)
+          const finalResult = parseContent(accumulatedContent, options)
           yield {
             chunk: '',
             body: finalResult.body,
@@ -289,7 +324,7 @@ export async function* parseStreamIncremental(
         const closedContent = autoCloseMarkdown(accumulatedContent)
 
         // Parse the auto-closed content
-        const result = parseContent(closedContent)
+        const result = parseContent(closedContent, options)
 
         yield {
           chunk: chunkStr,

src/types.ts

@@ -0,0 +1,17 @@
+export interface ParseOptions {
+  /**
+   * Whether to automatically unwrap single paragraphs in container components.
+   * When enabled, if a container component (alert, card, callout, note, warning, tip, info)
+   * has only a single paragraph child, the paragraph wrapper is removed and its children
+   * become direct children of the container. This creates cleaner HTML output.
+   *
+   * @default true
+   * @example
+   * // With autoUnwrap: true (default)
+   * // <alert><strong>Text</strong></alert>
+   *
+   * // With autoUnwrap: false
+   * // <alert><p><strong>Text</strong></p></alert>
+   */
+  autoUnwrap?: boolean
+}

src/utils/auto-unwrap.ts

@@ -0,0 +1,90 @@
+import type { MDCElement } from '../types/tree'
+
+// Node types that can be containers (for auto unwrap feature)
+const CONTAINER_NODE_TYPES = new Set([
+  'alert',
+  'card',
+  'callout',
+  'note',
+  'warning',
+  'tip',
+  'info',
+])
+
+// Node types that should not be unwrapped
+const NON_UNWRAPPABLE_TYPES = new Set([
+  'pre',
+  'code',
+  'table',
+  'thead',
+  'tbody',
+  'tr',
+  'th',
+  'td',
+  'ul',
+  'ol',
+  'li',
+  'blockquote',
+])
+
+/**
+ * Applies automatic unwrapping to container components.
+ *
+ * This utility removes unnecessary paragraph wrappers from container component children.
+ * If a container has only a single paragraph child (and no other block elements),
+ * the paragraph is unwrapped and its children are hoisted up to be direct children
+ * of the container.
+ *
+ * @param node - The MDC element to process
+ * @returns The node with auto-unwrapped children (if applicable)
+ *
+ * @example
+ * // Before:
+ * { tag: 'alert', children: [{ type: 'element', tag: 'p', children: [{ type: 'text', value: 'Text' }] }] }
+ *
+ * // After:
+ * { tag: 'alert', children: [{ type: 'text', value: 'Text' }] }
+ */
+export function applyAutoUnwrap(node: MDCElement): MDCElement {
+  // Only apply to container components
+  if (!CONTAINER_NODE_TYPES.has(node.tag)) {
+    return node
+  }
+
+  // Don't unwrap if there are no children
+  if (node.children.length === 0) {
+    return node
+  }
+
+  // Filter out empty text nodes for checking
+  const nonEmptyChildren = node.children.filter(child =>
+    child.type !== 'text' || (child.value && child.value.trim()),
+  )
+
+  // Check if we have exactly one paragraph child (and possibly empty text nodes)
+  const paragraphs = nonEmptyChildren.filter(
+    child => child.type === 'element' && child.tag === 'p',
+  )
+
+  // Also check for other non-unwrappable elements (lists, code blocks, etc.)
+  const hasNonUnwrappableElements = nonEmptyChildren.some(
+    child => child.type === 'element'
+      && child.tag !== 'p'
+      && (NON_UNWRAPPABLE_TYPES.has(child.tag) || child.tag === 'template'),
+  )
+
+  // Only unwrap if:
+  // 1. There's exactly one paragraph
+  // 2. No other non-unwrappable elements (lists, code blocks, etc.)
+  if (paragraphs.length === 1 && !hasNonUnwrappableElements) {
+    const paragraph = paragraphs[0] as MDCElement
+    // Unwrap: return the paragraph's children as the container's direct children
+    return {
+      ...node,
+      children: paragraph.children,
+    }
+  }
+
+  // Otherwise, keep the structure as-is
+  return node
+}