comark

Comark - 技能指南

一款高性能 Markdown 解析器，支持 Comark（Markdown 中的组件），基于 markdown-it 构建，同时提供基于字符串和流式 API。

概述

Comark 在保持与 CommonMark 和 GitHub Flavored Markdown 完全兼容的同时，通过强大的组件系统扩展了标准 Markdown。它提供：

• 🚀 使用 markdown-it 引擎进行高性能解析
• 📦 支持流式处理，提供缓冲和增量模式
• ⚡ 支持实时渲染，并可自动闭合不完整语法
• 🔧 支持用于自定义组件的 Comark 组件语法
• 🎨 提供 Vue、React、Svelte 和 Angular 渲染器，支持自定义组件映射
• 📝 支持 YAML frontmatter
• 📑 自动生成目录
• 🎯 全面支持 TypeScript
• 🌈 集成 Shiki，支持语法高亮

软件包信息

• 软件包名称： comark
• 安装： npm install comark 或 pnpm add comark
• 导出：
  • 主解析器：comark
  • Vue 组件：@comark/vue
  • React 组件：@comark/react
  • Svelte 组件：@comark/svelte
  • Angular 组件：@comark/angular
  • HTML 渲染：@comark/html
  • ANSI 终端渲染：@comark/ansi
  • Nuxt 模块：@comark/nuxt

快速入门

基本用法

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 渲染

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

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

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

React 渲染

import { Markdown } from '@comark/react'

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

Svelte 渲染

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

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

<Markdown value={content} />

Angular 渲染

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`
}

文档章节

本指南分为多个专题章节，介绍软件包的不同方面：

📝 1. Markdown 语法

通过完整的语法参考，了解如何编写 Comark 文档：

• 标准 Markdown： 标题、文本格式、列表、链接、图片、引用块
• Frontmatter： 包含特殊字段（title、depth、searchDepth）的 YAML 元数据
• Comark 组件： 块级组件（::component）、行内组件（:component）、属性、插槽、嵌套
• 属性： 使用 {...} 语法为原生 Markdown 元素添加自定义属性
• 代码块： 语言指定、文件名元数据、行高亮、特殊字符
• 任务列表： 使用 [x] 和 [ ] 语法的 GFM 风格复选框
• 表格： 支持对齐和行内 Markdown 的 GFM 表格

→ 阅读完整的 Markdown 语法指南

---

🔧 2. 解析与文档模型

关于解析和使用 MarkdownDocument 的完整指南：

• 字符串解析： 带选项（autoUnwrap、autoClose）的 parseMarkdown() 函数
• 异步解析： 支持 Shiki 语法高亮的 parseMarkdown()
• 文档结构： 采用紧凑数组节点且可序列化的 MarkdownDocument
• 渲染文档： 转换为 HTML（通过 @comark/html 使用 renderHtmlFromDocument）或 Markdown（通过 comark/render 使用 renderMarkdown）
• 自动闭合： 自动闭合未闭合的语法
• 自动解包： 移除容器组件中不必要的段落包装

→ 阅读完整的解析与文档模型指南

---

⚛️ 3. Vue 渲染

在 Vue 应用中进行渲染的综合指南：

• 基本用法： 设置 Markdown 组件
• 自定义组件： 将自定义 Vue 组件映射到 Comark 元素
• 动态加载： 使用 componentsManifest 加载延迟组件
• 插槽支持： 使用 #slot-name 语法的具名插槽
• 流式模式： 使用响应式内容进行实时渲染
• Prose 组件： 为标准元素预先构建的样式化组件
• 错误处理： 内置错误捕获功能，适用于流式处理场景
• 属性访问： 访问 __node 和已解析的属性

→ 阅读完整的 Vue 渲染指南

---

⚛️ 4. React 渲染

React 应用中的渲染综合指南：

• 基本用法： 设置 Markdown 组件
• 自定义组件： 将自定义 React 组件映射到 Comark 元素
• 动态加载： 使用 componentsManifest 延迟加载组件
• Props 转换： 自动转换 HTML 属性（class → className 等）
• 流式模式： 使用响应式内容实时渲染
• Prose 组件： 为标准元素预先构建的样式组件
• 自定义 Props： 访问已解析的属性和 __node
• CSS 类名： 自定义包装类和 Tailwind CSS 集成

→ 阅读完整的 React 渲染指南

---

🎡 5. Svelte 渲染

Svelte 5 应用中的渲染综合指南：

• 基本用法： 使用 $state 设置 Markdown 组件
• 自定义组件： 将自定义 Svelte 组件映射到 Comark 元素
• 动态加载： 使用 componentsManifest 延迟加载组件
• Props 映射： 属性到 prop 的转换（接近 HTML 语义）
• 流式模式： 使用响应式 $state 实时渲染
• 实验性异步功能： 使用 <svelte:boundary> 的 MarkdownAsync
• Prose 组件： 使用 Prose 前缀覆盖原生 HTML 元素

→ 阅读完整的 Svelte 渲染指南

---

🅰️ 6. Angular 渲染

Angular 17+ 应用中的渲染综合指南：

• 基本用法： 设置独立的 Markdown 组件
• 自定义组件： 将 Angular 组件映射到 Comark 元素
• 组件解析： Prose{PascalTag}、PascalTag、tag 的优先级顺序
• 内容投影： 通过 <ng-content select="[slot=name]"> 使用命名插槽
• 流式模式： 使用插入符指示器实时渲染
• 数据绑定： 使用环境 data 输入解析 :binding
• 预配置组件： defineMarkdownComponent 和 defineMarkdownDocumentComponent
• 插件： 使用 Angular 组件包装器的 Math（KaTeX）、Mermaid、Binding

→ 阅读完整的 Angular 渲染指南

---

🤖 7. 与 AI Agent 配合使用

在 AI Agent 和大模型流式工作流中集成 Comark 的指南：

• 大模型流式输出： 实时渲染增量 AI 输出
• 自动闭合： 处理不完整的大模型部分 token 语法
• 插入符指示器： 在生成过程中显示实时光标
• 框架示例： Vue、React、Svelte、Angular 流式模式
• CLI 的 ANSI： 在终端 Agent 中渲染 AI 输出

→ 阅读完整的 Agent 指南

---

深入了解关键特性

Comark 组件语法

Comark 在保留 Markdown 可读性的同时扩展了自定义组件：

::alert{type="warning" .important}
This is a **warning** message with markdown support.
::


Check out this :icon-star{.text-yellow} component.


::card
#header
## Title

#content
Main content

#footer
Footer
::

Markdown 文档模型

基于轻量级数组的结构，可高效处理：

interface MarkdownDocument {
  nodes: [
    ["h1", { "id": "hello" }, "Hello"],
    ["p", {}, "Text with ", ["strong", {}, "bold"], " word"],
    ["alert", { "type": "info" }, "Message"]
  ],
  frontmatter: {},
  meta: {}
}

常见用例

1. 静态站点生成器

import { parseMarkdown } from 'comark'
import { renderHtmlFromDocument } from '@comark/html'
import shiki from '@comark/html/plugins/shiki'

async function processMarkdownFile(filePath: string) {
  const content = await readFile(filePath, 'utf-8')

  const doc = await parseMarkdown(content, {
    plugins: [
      shiki({
        themes: { light: 'github-dark', dark: 'github-dark' },
      }),
    ],
  })

  return {
    html: await renderHtmlFromDocument(doc),
    frontmatter: doc.frontmatter,
    toc: doc.meta.toc
  }
}

2. 实时 Markdown 编辑器

import { useState } from 'react'
import { Markdown } from '@comark/react'

export default function Editor() {
  const [content, setContent] = useState('# Hello')

  return (
    <div className="split-editor">
      <textarea value={content} onChange={e => setContent(e.target.value)} />
      <Markdown value={content} />
    </div>
  )
}

3. 批量文件处理

import { readFile } from 'node:fs/promises'
import { parseMarkdown } from 'comark'

async function processMultipleFiles(files: string[]) {
  const results = await Promise.all(
    files.map(async (file) => {
      const content = await readFile(file, 'utf-8')
      return await parseMarkdown(content)
    })
  )

  results.forEach((result, i) => {
    console.log(`File ${files[i]}:`)
    console.log(`  - ${result.nodes.length} nodes`)
  })
}

4. 文档平台

<template>
  <article class="prose">
    <Markdown :value="markdownContent" :components="docComponents" />
  </article>
</template>

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

API 参考概要

核心函数（comark）

// Asynchronous parsing
parseMarkdown(source: string, options?: ParserOptions): Promise<MarkdownDocument>

// Auto-close unclosed syntax
autoCloseMarkdown(source: string): string

HTML 渲染函数（@comark/html）

// Render markdown to HTML string (parse + render in one step)
renderHtml(markdown: string, options?: ParserOptions & RendererOptions): Promise<string>

// Render a pre-parsed document to HTML
renderHtmlFromDocument(document: MarkdownDocument, options?: RendererOptions): Promise<string>

// Create a reusable render function with shared parser instance
createHtmlRenderer(options?: ParserOptions & RendererOptions): (markdown: string) => Promise<string>

Vue 组件（@comark/vue）

<Markdown :value="markdownString" :components="customComponents" />

React 组件（@comark/react）

<Markdown value={markdownString} components={customComponents} />

Svelte 组件（@comark/svelte）

<Markdown value={markdownString} components={customComponents} />

Angular 组件（@comark/angular）

<comark-markdown [value]="markdownString" [components]="customComponents" />

性能特征

• 可序列化文档模型 - 基于紧凑数组的节点
• 延迟加载组件 - 只加载所需内容
• Shiki 高亮器缓存 - 避免重新初始化
• 并行处理 - 高效地批量解析多个文件

TypeScript 支持

包含完整的 TypeScript 类型定义：

import type {
  MarkdownDocument,
  Node,
  ParserOptions,
} from 'comark'

架构概览

┌─────────────────────────────────────────┐
│         Markdown Input (String)         │
└────────────────┬────────────────────────┘
                 │
        ┌────────▼────────┐
        │  Auto-close     │ (Optional)
        │  Unclosed       │
        │  Syntax         │
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  Parse          │
        │  Frontmatter    │ (YAML)
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  MarkdownIt     │
        │  + Plugins      │ (Comark, Tasks)
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  Token          │
        │  Processing     │
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  Comark         │
        │  AST            │
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  Auto-unwrap    │ (Optional)
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  Generate TOC   │
        └────────┬────────┘
                 │
        ┌────────▼────────┐
        │  MarkdownDocument     │
        │  (nodes + data  │
        │   + meta)       │
        └────────┬────────┘
                 │
     ┌───────────┬──────┴──────┬───────────┐
     ▼           ▼            ▼           ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│   Vue   │ │  React  │ │ Svelte  │ │ Angular │
│ Renderer│ │ Renderer│ │ Renderer│ │ Renderer│
└─────────┘ └─────────┘ └─────────┘ └─────────┘

贡献与测试

如需了解所有受支持语法功能的示例，请参阅测试规范。

运行测试：

pnpm test

运行指定测试：

pnpm test -- tests/parse.test.ts

资源

• README： README.md - 安装和快速入门
• 规范： SPEC/ - 完整的语法测试用例

---

总结

Comark 是一款功能全面的解决方案，可用于解析和渲染支持组件的 Markdown。它擅长：

1. 扩展 Markdown - 添加组件语法，同时保持兼容性
2. 流式支持 - 实时渲染并自动闭合
3. 可序列化文档 - 高效的 MarkdownDocument 模型，采用紧凑节点
4. 框架支持 - 一流地集成 Vue、React、Svelte 和 Angular
5. 开发者体验 - 完整的 TypeScript 支持和全面的文档

在以下场景中选择 Comark：

• 需要带自定义组件的 Markdown
• 流式／增量解析
• 实时 Markdown 编辑器
• AI 生成内容的渲染
• 文档平台
• 使用自定义组件生成静态网站

---

后续步骤：

• 📝 学习 Markdown 语法
• 🔧 掌握解析与 AST
• ⚛️ 探索 Vue 渲染
• ⚛️ 探索 React 渲染
• 🎡 探索 Svelte 渲染
• 🅰️ 探索 Angular 渲染
• 🤖 与 AI Agent 搭配使用