markdown

assistant-ui Markdown

最新の API については、常に assistant-ui.com/llms.txt を参照してください。

assistant-ui には、アシスタントのテキストパート用のレンダラーが 2 つあります。MarkdownTextPrimitive は軽量な react-markdown の経路であり、インストールされる MarkdownText 要素はそのスタイル付き実装です。StreamdownTextPrimitive は、ブロック単位のストリーミングと、オプションの Shiki、KaTeX、Mermaid、CJK サポートのために、より大きなレンダラーを受け入れる場合の代替手段です。

リファレンス

• ./references/markdown-text.md -- MarkdownText のインストールと構成、MarkdownTextPrimitive のカスタマイズ、インラインコードとフェンス付きコードの区別
• ./references/syntax-highlighting.md -- Shiki または Prism レンダラーのインストールと、フェンス付き言語ごとの選択
• ./references/latex-mermaid.md -- KaTeX の設定、モデルの数式の正規化、コードスパンの保持、ストリーム完了時の Mermaid のゲート
• ./references/streamdown.md -- Streamdown の代替手段、プラグイン、Tailwind ソース、遅延パースの使用

レンダラーの選択

アプリが小さなレンダラー、カスタムの react-markdown コンポーネントマップ、または言語ごとの SyntaxHighlighter と CodeHeader のオーバーライドを必要とする場合は、markdown-text を使用してください。ハイライト、数式、Mermaid は、メッセージ形式がそれらを必要とする場合にのみ追加してください。

テキストパートがブロック単位のストリーミング、不完全な markdown の修復、またはオプションのコード、数式、Mermaid、CJK プラグインを必要とする場合は、StreamdownTextPrimitive を使用してください。これはそのテキストパートの markdown レンダラーを置き換えます。同じパートに対して両方のレンダラーをマウントしないでください。

MarkdownText のインストールと接続

レンダラーをインストールします。これは components/assistant-ui/elements/markdown-text.tsx に配置されます。

npx assistant-ui@latest add markdown-text

MarkdownText はアクティブなメッセージパート自体を読み取ります。これを text ブランチにのみレンダリングし、他のパート種別はそれぞれ独自のレンダラーを維持します。

"use client";

import { MessagePrimitive } from "@assistant-ui/react";
import { MarkdownText } from "@/components/assistant-ui/elements/markdown-text";

export function AssistantMessageText() {
  return (
    <MessagePrimitive.Parts>
      {({ part }) => (part.type === "text" ? <MarkdownText /> : null)}
    </MessagePrimitive.Parts>
  );
}

thread 要素にはすでにこのレンダラーが含まれています。スレッドのメッセージレイアウトを置き換える場合にのみ、これを直接構成してください。

プリミティブのカスタマイズ

MarkdownTextPrimitive はコンテキストを介して周囲のテキストパートを読み取るため、text の子要素や value プロパティを受け取りません。その components マップは通常の markdown タグに加えて SyntaxHighlighter と CodeHeader を制御し、componentsByLanguage は 1 つのフェンス付き言語に対してどちらかのスロットを置き換えます。プリミティブを直接実装する方法については、markdown-text.md を参照してください。

preprocess は、スムージングとパースの前に、蓄積された完全なテキストに対して実行されます。これはモデル固有の区切り文字修復のための接点です。smooth のデフォルトは true、defer のデフォルトは false です。React が中間パースよりも入力とスクロールを優先すべき、大きく急速に増加するメッセージには defer を設定してください。切り替えるとパース済みツリーが再マウントされるため、レンダラーのマウント中はその値を一定に保ってください。

フェンス付きコードのハイライト

MarkdownText は、SyntaxHighlighter が登録されるまでフェンス付きコードをプレーンなコードとして表示します。トークン化の前にアクティブなパートが確定するのを待つ、ランタイム対応の Shiki 要素を推奨します。

npx assistant-ui@latest add shiki-highlighter

import { SyntaxHighlighter } from "@/components/assistant-ui/elements/shiki-highlighter.aui";

const defaultComponents = memoizeMarkdownComponents({
  SyntaxHighlighter,
});

Prism ベースの syntax-highlighter 要素は、すでに react-syntax-highlighter に依存しているアプリには引き続き有用です。

npx assistant-ui@latest add syntax-highlighter

import { SyntaxHighlighter } from "@/components/assistant-ui/elements/syntax-highlighter";

インストールされた markdown-text コンポーネントのデフォルトマップを編集するか、要素がレンダリングされる場所で components オーバーライドを渡してください。正確なレンダラー契約については、syntax-highlighting.md を参照してください。

数式と図をレンダリングする

KaTeX には remark-math、rehype-katex、および KaTeX スタイルシートが必要です。markdown パッケージは、モデル出力の前処理用に normalizeMathDelimiters、rewriteCustomMathTags、rewriteLatexBracketDelimiters、escapeCurrencyDollars をエクスポートします。これらのヘルパーはインラインコードとフェンスコードの外側を書き換えるため、コード内の例はそのままの状態で保たれます。

mermaid-diagram をインストールし、その .aui レンダラーを mermaid 言語オーバーライドとして登録します。これはメッセージパートのステータスを読み取り、不完全な Mermaid ソースを解析するのではなく、ストリームの実行中はスケルトンを表示します。latex-mermaid.md を参照してください。

代わりに Streamdown を使用する

StreamdownTextPrimitive は同じテキストパートのコンテキストを読み取り、同じ MessagePrimitive.Parts ブランチに組み込むことができます。デフォルトは mode="streaming" で、最後のブロックが成長する間、完了したブロックを安定した状態に保ちます。オプションのプラグインは明示的に指定し、Streamdown とインストールした各プラグインに Tailwind の @source エントリを追加して、そのコントロールとキャレットにスタイルが適用されるようにします。

ここでは defer と smooth の両方が利用できます。defer のデフォルトは false で、負荷が高い状況では中間状態をスキップすることがありますが、最終的なテキストは引き続きレンダリングされます。smooth もデフォルトは false です。タイプライター風の表示を特に希望しない限り、登場アニメーションには Streamdown ネイティブの animated プロップを使用してください。完全なセットアップと移行の接点については streamdown.md を参照してください。

よくある落とし穴

Markdown がプレーンテキストとしてレンダリングされる

• text ブランチで MarkdownText または StreamdownTextPrimitive をレンダリングしてください。part.text を直接レンダリングすると、markdown の解析がバイパスされます。

フェンスコードにシンタックスの色が付かない

• markdown-text にはラベルとコピーコントロールが含まれますが、ハイライターは含まれません。shiki-highlighter または syntax-highlighter をインストールして登録してください。

数式がスタイルなしで出力される、または価格が数式になる

• KaTeX のために katex/dist/katex.min.css を一度インポートしてください。メッセージに単一ドルの数式と通貨の両方が含まれる場合は、escapeCurrencyDollars(normalizeMathDelimiters(text)) を組み合わせてください。

レスポンスのストリーミング中に Mermaid が再描画される

• componentsByLanguage で @/components/assistant-ui/elements/mermaid-diagram.aui を使用してください。そのランタイムラッパーは、メッセージパートが完了するまで解析を保留します。

遅延解析によって視覚的なリセットが発生する

• マウント後に defer を切り替えないでください。このプロップが変更されると、両方のプリミティブは異なる遅延レンダラーパスを選択します。

Streamdown のコントロールやキャレットにスタイルが適用されていない

• streamdown およびインストールしたすべての @streamdown/* プラグインに必要な Tailwind の @source ディレクティブを追加してください。

関連スキル

• primitives -- MessagePrimitive.Parts とその周辺のメッセージ UI を構成します
• elements -- コピーした markdown-text、ハイライター、Mermaid 要素のソースをインストールしてカスタマイズします