rspress-plugin-plantuml

Rspress のページ表示時に、plantuml のフェンス付きコードブロックをインライン SVG として描画するプラグインです。描画には JavaScript のみで動作する @plantuml/core を使用します。 Rspress のビルド時には図を描画せず、ブラウザー上で描画します。

動作要件

• Node.js 20 以降
• Rspress 2

Java、PlantUML JAR、OS にインストールした Graphviz、および PlantUML Server は 不要です。@plantuml/core には JavaScript 版の Graphviz レイアウトエンジンが 含まれています。

インストール

npm install rspress-plugin-plantuml

Rspress の設定

import { defineConfig } from '@rspress/core';
import { pluginPlantUml } from 'rspress-plugin-plantuml';

export default defineConfig({
  plugins: [pluginPlantUml()],
});

図の記述

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

フェンス付きコードブロックは、コンパイル時にプレースホルダーへ変換されます。 ページが表示されると、ブラウザーがサニタイズ済みのインライン <svg> として 描画します。ほかの言語のフェンス付きコードブロックは変更しません。 クライアントサイドのページ遷移も監視するため、遷移先の図も描画されます。

描画はブラウザー上で行われるため、PlantUML の構文が不正でも Rspress のビルドは 失敗しません。描画に失敗した場合は、図の代わりにエラーメッセージを表示します。

include、スプライト、テーマ

このプラグインは、ファイルシステムやネットワークからリソースを読み込むための アダプターを意図的に提供していません。

• !include でプロジェクト内の任意のファイルを読み込むことはできません。
• !includeurl による HTTP リクエストは行いません。
• 現在の @plantuml/core npm パッケージには、容量の大きいオプションの スプライトライブラリは含まれていません。インラインのスプライト定義は エンジンの構文として利用できます。
• テーマと標準ライブラリは、インストールされた @plantuml/core にコンパイル済み、 または同梱されているリソースに限られます。

要求されたリソースを利用できない場合は描画に失敗します。Java、サーバー、外部 コマンドへフォールバックすることはありません。

セキュリティ

生成された SVG は、挿入前にブラウザー上で解析します。スクリプトを実行できる 要素、イベントハンドラー属性、および javascript:、vbscript:、data: の URL 属性を除去します。描画に失敗したコードブロックを暗黙に残すことはありません。