comark

Comark - スキルガイド

Comark（Markdown 内のコンポーネント）をサポートする高性能な Markdown パーサーです。markdown-it を基盤とし、文字列ベースとストリーミングの両方の API を提供します。

概要

Comark は、CommonMark および GitHub Flavored Markdown との完全な互換性を維持しながら、強力なコンポーネントシステムで標準の Markdown を拡張します。次の機能を提供します。

• 🚀 markdown-it エンジンによる 高性能な解析
• 📦 バッファリングモードと増分モードによる ストリーミングのサポート
• ⚡ 未完了の構文を自動で閉じる リアルタイムレンダリング
• 🔧 カスタムコンポーネント向けの Comark コンポーネント構文
• 🎨 カスタムコンポーネントのマッピングに対応した Vue、React、Svelte、Angular のレンダラー
• 📝 YAML フロントマターのサポート
• 📑 目次の自動生成
• 🎯 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： 見出し、テキストの書式設定、リスト、リンク、画像、引用
• フロントマター： 特別なフィールド（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 コンポーネント： 標準要素向けの、スタイル設定済みコンポーネント
• エラー処理： ストリーミング時に使用できる組み込みのエラー捕捉機能
• Props へのアクセス： __node と解析済みプロパティへのアクセス

→ Vue レンダリングガイド全文を読む

---

⚛️ 4. React Rendering

React アプリケーションでのレンダリングに関する包括的なガイドです。

• 基本的な使い方： Markdown コンポーネントのセットアップ
• カスタムコンポーネント： カスタム React コンポーネントを Comark 要素にマッピング
• 動的読み込み： 遅延読み込みされるコンポーネントのための componentsManifest
• Props の変換： HTML 属性の自動変換（class → className など）
• ストリーミングモード： リアクティブなコンテンツのリアルタイムレンダリング
• Prose コンポーネント： 標準要素向けのスタイル設定済みコンポーネント
• カスタム Props： パース済みプロパティと __node へのアクセス
• CSS クラス名： カスタムラッパークラスと Tailwind CSS の統合

→ React レンダリングガイド全文を読む

---

🎡 5. Svelte Rendering

Svelte 5 アプリケーションでのレンダリングに関する包括的なガイドです。

• 基本的な使い方： $state を使った Markdown コンポーネントのセットアップ
• カスタムコンポーネント： カスタム Svelte コンポーネントを Comark 要素にマッピング
• 動的読み込み： 遅延読み込みされるコンポーネントのための componentsManifest
• Props のマッピング： 属性から Props への変換（HTML のセマンティクスに近い形式）
• ストリーミングモード： リアクティブな $state によるリアルタイムレンダリング
• 実験的な非同期処理： <svelte:boundary> を使った MarkdownAsync
• Prose コンポーネント： ネイティブ HTML 要素をオーバーライドするための Prose プレフィックス

→ Svelte レンダリングガイド全文を読む

---

🅰️ 6. Angular Rendering

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 エージェントでの使用

AI エージェントと LLM のストリーミングワークフローに Comark を統合するためのガイドです。

• LLM からのストリーミング： AI の出力を逐次的にリアルタイムでレンダリング
• 自動クローズ： LLM の部分トークンによる未完了の構文への対応
• キャレットインジケーター： 生成中にライブカーソルを表示
• フレームワークの例： Vue、React、Svelte、Angular のストリーミングパターン
• CLI 向け ANSI： ターミナルエージェントで AI の出力をレンダリング

→ エージェントガイド全文を読む

---

主な機能の詳細

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 エージェントと連携して使用する