はじめに
@powerduck/md-editor は、ブラウザーに 組み込める高性能な Markdown エディターです。CodeMirror 6 の編集領域と markdown-it によるライブプレビューを組み合わせ、KaTeX 数式、Markmap マインドマップ、コードのハイライト、注記ブロック、設定可能なツールバー、キーボードショートカット、画像アップロード用フック、@メンション、ドキュメントリンクの挿入に対応しています。
- パッケージ名：
@powerduck/md-editor - ライセンス： MIT
- モジュール形式： ECMAScript モジュール（
type: "module"）。ESM（dist/index.mjs）と CJS（dist/index.cjs）の両方のビルド、および型宣言（dist/index.d.ts）を提供します。
主な機能
以下は、実装済みのソースモジュールに対応する機能です。
- Markdown 編集： CodeMirror 6 を使用し、Markdown の構文ハイライトとライト・ダークのハイライトテーマに対応します。
- KaTeX 数式： 独立した markdown-it プラグインで、インラインの
$...$とブロックの$$...$$に対応します。$5のような金額は、ヒューリスティックな判定で数式解析から除外します。 - Markmap マ インドマップ：
```mindmapのフェンス付きブロックから描画します。markmap-lib と markmap-view は動的にインポートされるため、マインドマップがない場合に初期バンドルを増やしません。 - コードのハイライト： highlight.js を使用し、macOS 風の 3 色の丸を備えたヘッダー、言語ラベル、ワンクリックのコピーボタンを表示します。
- 注記ブロック：
:::notice、:::info、:::tip、:::success、:::warning、:::dangerにアイコンと色分けを適用します。 - GitHub 風プレビュー：
github-markdown-cssを使用します。 - 充実したツールバー： 22 の操作、画像・動画・YouTube・表の挿入ダイアログ、数式とマインドマップのテンプレート選択、すべてのショートカットを確認できるヘルプを備えています。
- キーボードショートカット：
Modは Windows/Linux では Ctrl、macOS では Cmd に対応します。 - ツールバーの設定： 表示する項目の配列、または項目ごとの
show、label、iconの設定でカスタマイズできます。 - 画像アップロード用フック： エディターに画像を貼り付けるかドロップすると、
onImageUploadを呼び出します。 - @メンションのドロップダウン：
mentionオプションで設定します。選択したメンションはプレビューで装飾付きのバッジになります。 - ドキュメントリンクの挿入：
docLinkで設定し、通常のリンクまたは:::doc-linkプレビューカードを挿入します。メタデータは組み込みローダーまたはカスタムフックで取得します。オリジンをまたぐリクエストにはブラウザーの CORS ルールが適用されます。 - 動画表示： 画像構文の URL が
.mp4、.webm、.oggなどの既知の拡張子で終わる場合、<video controls>要素として描画します。 - 単独レンダラー：
renderMarkdown(source, options)は、エディターをマウントせずに、プレビューと同じプラグインとスタイルを使った HTML を生成します。 - ブロック単位の差分描画： ATX 見出しでソースを分割し、変更されたブロックだけを再描画します。変更のないブロックは、初期化済みのマインドマップ SVG を含む既存の DOM ノードを再利用します。描画結果は内容のハッシュでキャッシュします。
- 適応型デバウンス： プレビュー描画までの待機時間は文書の長さに応じて変わり、基本値は 120 ミリ秒、上限は 600 ミリ秒です。
- 2 つの編集モード：
simpleはツールバーなしの編集とプレビュー、complexはツールバーとステータスバーを備え、実行時に切り替えられます。 - 2 つのテーマ：
lightとdarkを、data-theme属性と CSS カスタムプロパティで適用します。
アーキテクチャの概要
ライブラリーは 2 種類のインターフェースを提供します。
-
ネイティブ JavaScript クラス： 主な API は、コンテナー要素を指定して作成する
MarkdownEditorを中心に構成されます。内部にはCodeEditor（CodeMirror のラッパー）、Renderer（markdown-it のラッパー）、プレビュー用のIncrementalRendererがあり、complexモードではToolbarとStatusBarも使用します。ダイアログ、@メンションコントローラー、ドキュメントリンクコントローラーは、必要に応じてマウントするモジュールです。 -
React サブパスのエクスポート：
MarkdownEditorReactは./reactからエクスポートされるforwardRefコンポーネントです。ネイティブのMarkdownEditorインスタンスをラップし、制御・非制御のvalueに対応して、ref 経由で命令型のMarkdownEditorHandleを公開します。React 用の入り口は分離されているため、React を使わないプロジェクトにreactとreact-domのインストールは不要です。
描画は、マインドマップ用のプレースホルダー HTML を生成する同期の markdown-it 処理と、Renderer.hydrate でプレースホルダーを対話可能な SVG に変換する非同期の初期化処理に分かれます。renderMarkdown が返すのは同期 HTML です。マインドマップの SVG が必要な場合は Renderer.render を使い、HTML を DOM に挿入してから Renderer.hydrate を呼び出し てください。差分レンダラーはプレビューコンテナーを直接操作します。
ブラウザー対応
DOM を備えたモダンブラウザーを対象としています。CodeMirror 6、KaTeX、markmap-view はブラウザーの機能ではなく、パッケージの依存関係です。対話可能なマインドマップは ResizeObserver を使用します。Clipboard API が利用できる場合はそれを使用し、HTTPS 以外の環境などで navigator.clipboard が使えない場合は、コードブロックのコピーに document.execCommand('copy') を使用します。マインドマップモジュールは、グローバルの ResizeObserver が未定義の場合に限り空の実装を登録し、未定義によるインポートエラーを防ぎます。この実装は実際のサイズ変更を通知しません。
ライセンス
@powerduck/md-editor は MIT ライセンスで公開されています。