/comark

name: comark
description: 'Comark (Components in Markdown) parser: syntax, AST, Vue/React/Svelte/Angular renderers, plugins, and LLM streaming with auto-close.'

Comark - Skills Guide

A high-performance markdown parser with Comark (Components in Markdown) support, built on markdown-it, offering both string-based and streaming APIs.

Overview

**Comark** extends standard markdown with a powerful component system while maintaining full compatibility with CommonMark and GitHub Flavored Markdown. It provides:

• 🚀 **High-performance parsing** with markdown-it engine
• 📦 **Streaming support** with buffered and incremental modes
• ⚡ **Real-time rendering** with auto-close for incomplete syntax
• 🔧 **Comark component syntax** for custom components
• 🎨 **Vue, React, Svelte & Angular renderers** with custom component mapping
• 📝 **YAML frontmatter** support
• 📑 **Automatic TOC generation**
• 🎯 **Full TypeScript support**
• 🌈 **Syntax highlighting** with Shiki integration

Package Information

• **Package Name:** `comark`
• **Installation:** `npm install comark` or `pnpm add comark`
• **Exports:**
• Main parser: `comark`
• Vue components: `@comark/vue`
• React components: `@comark/react`
• Svelte components: `@comark/svelte`
• Angular components: `@comark/angular`
• HTML rendering: `@comark/html`
• ANSI terminal rendering: `@comark/ansi`
• Nuxt module: `@comark/nuxt`

Quick Start

Basic Usage

import { parseMarkdown } from 'comark'

const content = `---
title: Hello World
---

# Hello World

This is **markdown** with :icon component.

::alert{type="info"}
Important message
::
`

const result = await parseMarkdown(content)
console.log(result.nodes)       // Markdown AST
console.log(result.frontmatter) // { title: 'Hello World' }
console.log(result.meta)    // Additional metadata

Vue Rendering

<template>
  <Markdown :value="content" />
</template>

<script setup lang="ts">
import { Markdown } from '@comark/vue'

const content = `# Hello World`
</script>

React Rendering

import { Markdown } from '@comark/react'

export default function App() {
  return <Markdown value={content} />
}

Svelte Rendering

<script lang="ts">
  import { Markdown } from '@comark/svelte'

  const content = `# Hello World`
</script>

<Markdown value={content} />

Angular Rendering

import { Component } from '@angular/core'
import { Markdown } from '@comark/angular'

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [Markdown],
  template: `<comark-markdown [value]="content" />`,
})
export class AppComponent {
  content = `# Hello World`
}

Documentation Sections

This guide is organized into focused sections covering different aspects of the package:

📝 [1. Markdown Syntax](./references/markdown-syntax.md)

Learn how to write Comark documents with complete syntax reference:

• **Standard Markdown:** headings, text formatting, lists, links, images, blockquotes
• **Frontmatter:** YAML metadata with special fields (title, depth, searchDepth)
• **Comark Components:** block components (`::component`), inline components (`:component`), properties, slots, nesting
• **Attributes:** custom attributes on native markdown elements using `{...}` syntax
• **Code Blocks:** language specification, filename metadata, line highlighting, special characters
• **Task Lists:** GFM-style checkboxes with `[x]` and `[ ]` syntax
• **Tables:** GFM tables with alignment and inline markdown support

**[→ Read Full Markdown Syntax Guide](./references/markdown-syntax.md)**

---

🔧 [2. Parsing & Document Model](./references/parsing-ast.md)

Complete guide for parsing and working with `MarkdownDocument`:

• **String Parsing:** `parseMarkdown()` function with options (autoUnwrap, autoClose)
• **Async Parsing:** `parseMarkdown()` with Shiki syntax highlighting
• **Document Structure:** serializable `MarkdownDocument` with compact array-based nodes
• **Rendering Documents:** convert to HTML (`renderHtmlFromDocument` via `@comark/html`) or markdown (`renderMarkdown` via `comark/render`)
• **Auto-close:** automatic closing of unclosed syntax
• **Auto-unwrap:** remove unnecessary paragraph wrappers from container components

**[→ Read Full Parsing & Document Model Guide](./references/parsing-ast.md)**

---

⚛️ [3. Vue Rendering](./references/rendering-vue.md)

Comprehensive guide for rendering in Vue applications:

• **Basic Usage:** `Markdown` component setup
• **Custom Components:** mapping custom Vue components to Comark elements
• **Dynamic Loading:** `componentsManifest` for lazy-loaded components
• **Slots Support:** named slots with `#slot-name` syntax
• **Streaming Mode:** real-time rendering with reactive content
• **Prose Components:** pre-built styled components for standard elements
• **Error Handling:** built-in error capture for streaming scenarios
• **Props Access:** accessing `__node` and parsed properties

**[→ Read Full Vue Rendering Guide](./references/rendering-vue.md)**

---

⚛️ [4. React Rendering](./references/rendering-react.md)

Comprehensive guide for rendering in React applications:

• **Basic Usage:** `Markdown` component setup
• **Custom Components:** mapping custom React components to Comark elements
• **Dynamic Loading:** `componentsManifest` for lazy-loaded components
• **Props Conversion:** automatic HTML attribute conversion (`class` → `className`, etc.)
• **Streaming Mode:** real-time rendering with reactive content
• **Prose Components:** pre-built styled components for standard elements
• **Custom Props:** accessing parsed properties and `__node`
• **CSS Class Name:** custom wrapper classes and Tailwind CSS integration

**[→ Read Full React Rendering Guide](./references/rendering-react.md)**

---

🎡 [5. Svelte Rendering](./references/rendering-svelte.md)

Comprehensive guide for rendering in Svelte 5 applications:

• **Basic Usage:** `Markdown` com