レンダラプラグイン
数式・図・v1 互換記法を足すプラグインの有効化と設定
レンダラプラグインは、ページ本文の描画に数式や図を足します。書ける記法そのものは Markdown 記法、パイプラインの設計は レンダラパイプライン を参照してください。
有効化の手順は他のプラグインと同じで、runner プロジェクトの依存に加えて crowi.config.json の plugins に列挙します (プラグインの導入と設定)。
同梱されているレンダラプラグイン
| プラグイン | 役割 | 外部依存 | 設定 |
|---|---|---|---|
@crowi/plugin-renderer-katex | $inline$ / $$display$$ の数式を描画 | なし | なし |
@crowi/plugin-renderer-plantuml | ```plantuml ブロックを PlantUML サーバで描画 | PlantUML サーバ | サーバ URL・出力形式 |
@crowi/plugin-renderer-mermaid | ```mermaid ブロックをサーバ内で描画 | なし | なし |
@crowi/plugin-renderer-crowi-legacy | Crowi v1 由来の記法のクセを再現 (既定オフ) | なし | なし |
PlantUML
外部の PlantUML サーバが必要で、それは自分で用意します。Crowi の compose に PlantUML サービスは同梱されていません。
管理画面のプラグイン設定で サーバ URL と 出力形式 (svg / png) を指定してください。既定値は compose 内部のホスト名を指しているため、そのままでは解決できません。開発マシンで plantuml/plantuml-server を動かしているなら http://localhost:8080 です。
描画結果は 1 時間キャッシュされ、失敗は 5 分間キャッシュされます。過去に成功した図があれば、PlantUML サーバが一時的に落ちていても直前の図が表示され続けます。
Mermaid
設定は不要で、有効化するだけで使えます。図はブラウザではなくサーバ内で描画され、ページにはサニタイズ済みの画像として埋め込まれます。
制限値は次のとおりです。
- 図のソースは 20KB、生成される SVG は 60KB まで
- 1 回のページ保存・プレビューあたり同時に処理できる図は 50 個まで
- 並行描画は api プロセスごとに 4 個、1 ユーザーあたり同一プロセス内で 2 個まで (レプリカを増やすと合計はその分増えます)
- 編集中のプレビューは 1 ユーザーあたり 600 リクエスト / 60 秒
記法エラーのある図は固定のエラー表示になります。サーバの過負荷などで描画できなかった図は、そのページを次に開いたときに自動で再試行されます。
既存の ```mermaid フェンスは、著者がページを再保存するまでコードブロックのまま表示されます。プラグインを有効化しただけで過去のページが一括で描画し直されることはありません。
Note: 描画は外部へ出られない隔離子プロセスで行われますが、defense-in-depth として、コンテナ / OS レベルの egress 制御もあわせて検討してください。
crowi-legacy
Crowi v1 由来の、標準 Markdown ではない記法のクセ (ハッシュの直後に空白がない ##hoge を見出しとみなす、など) を再現する互換プラグインです。同梱されていますが 既定ではオフ で、v1 から移行したインスタンスが管理画面で有効化します。
プラグインではない描画機能
絵文字ショートコードとリンクカードは Crowi 本体の機能で、インストール不要・常時有効です。crowi.config.json の plugins にも現れません。
リンクカード (@[card](url)) だけは運用者向けの設定があります。
- 既定で有効です。 外部サイトへの OGP 取得を止めたい場合は、管理画面の「セキュリティ」→「外部リンクのカード化を許可する」で無効化できます。無効化するとその時点以降の新規レンダリングで DNS 解決も HTTP リクエストも発生しません。
- 無効時・取得失敗時・外部へ出られない環境では、同じフォールバックカードが表示されます。 OGP のタイトル・説明文・画像は含まず、URL 自体をタイトルとして表示する、リンクとして機能するカードです。
og:imageは取得元サイトへの直リンクとして埋め込まれます。プロキシやキャッシュ配信は行いません。- 取得先には SSRF ガードがあります。 private / loopback / メタデータ用アドレスに解決されるホストは拒否されます。
- トグルを切り替えても既存ページは作り直されません。 有効に戻した場合、既存ページのカードは次にそのページを保存またはレンダリングし直したときに反映されます。
- ドメイン単位の許可 / 拒否リストの設定はありません。
関連ページ
- Markdown 記法 — 利用者が書ける記法
- プラグインの導入と設定 — 有効化の手順
- レンダラパイプライン — 描画の仕組みと拡張点