markstream-custom-components

Markstream カスタムコンポーネント

Markstream が特定のノードやカスタムタグをどのようにレンダリングするか変更する場合に、このスキルを使用してください。

オーバーライド方法を選ぶ前に、references/patterns.md を読んでください。

ワークフロー

1. リクエストを分類します。
   • built-in override：image、link、code_block、mermaid、d2、inline_code など、既存のレンダラーを置き換えます。
   • custom tag：thinking のような信頼できる HTML 風タグに対応します。
   • parser-level：トークン変換や AST の再構成が必要です。この場合に限り、このスキルを離れて低レベルのパーサーフックを使用します。
2. スコープを限定したマッピングを優先します。
   • Vue、Vue 2、Svelte、および Angular の共有登録では、可能な限りグローバルマッピングの代わりに setCustomComponents(customId, mapping) を使用し、同じ customId / custom-id を渡します。
   • React のカスタムタグでは、パーサーが扱うノードにはレンダラー単位の streamingComponents を、サニタイズ済み HTML の props と children には htmlComponents を優先します。型付きマップには defineStreamingComponents(...) / defineHtmlComponents(...) を使用します。setCustomComponents は、組み込みノードのオーバーライドや共有のレガシー登録に使用します。
   • Svelte と Angular では、オーバーライドを共有レジストリに登録しない場合、レンダラー単位の customComponents マップも渡せます。
   • Vue 3 のアプリ／プラグインのセットアップで、オーバーライドを Vue アプリインスタンスに限定する場合は、markstream-vue から { VueRendererMarkdown } をインポートし、{ components } を指定してインストールします。
3. 最小限で安全なオーバーライドから始めます。
   • リーフノード（image、link、inline_code、mermaid）は、コンテナノード（heading、paragraph、list_item）より扱いやすいです。
   • Mermaid だけを変更するリクエストには、code_block ではなく mermaid を使用します。
4. 必要に応じて、ネストされた Markdown を保持します。
   • 内部に Markdown を含む信頼できるカスタムタグでは、ネストしたレンダラーで node.content をレンダリングします。
   • ネストしたレンダラーには、同じカスタムタグの許可リストを渡します。
   • スムーズストリーミングを行う親の内部にあるネストしたレンダラーは、二重ペーシングを防ぐため自動的に抑制されます。子レンダラーに smooth-streaming を追加しないでください。
   • React では、streamingComponents のキーが有効なカスタムタグのリストに自動的に追加されます。別のパーサーパスで必要な場合を除き、それらのキーを customHtmlTags に重複して指定しないでください。
5. props とクリーンアップを維持します。
   • node、loading、indexKey、customId、isDark を保持します。
   • mermaid と infographic のオーバーライドでは、再マウント時に非同期プレビューのシェルが高さを維持できるよう、estimatedPreviewHeightPx を保持します。
   • スコープが不要になったら、removeCustomComponents(customId) で一時的なスコープ付きマッピングを削除します。
6. 必要最小限のチェックで検証します。
   • ローカルデモ、対象を絞ったテスト、またはドキュメントのビルドを優先します。
   • 実装が、繰り返し使われるカスタムタグやネストしたカスタムタグに安全かどうかを明記します。

デフォルトの判断

• スコープ付きオーバーライドを優先し、アプリ全体で本当に必要な場合にのみグローバルオーバーライドを使用します。
• コンテナノードよりリーフノードのオーバーライドを優先します。
• パーサーフックより customHtmlTags とスコープ付きカスタムコンポーネントを優先します。
• React では、レジストリの変更よりレンダラー単位のコンポーネントマップを優先します。
• Markdown を含むタグの本文には、ネストしたレンダラーを使用します。

参考ドキュメント

• docs/guide/component-overrides.md
• docs/guide/custom-components.md
• docs/guide/react-components.md
• docs/guide/components.md
• docs/guide/advanced.md