AI活用

ComfyUIカスタムノードにヘルプを付ける|入力条件と失敗例の書き方

ComfyUIの自作ノードにMarkdownのヘルプを同梱する方法。WEB_DIRECTORY配下の配置、ノードIDと表示名の違い、多言語フォールバック、配布後の表示確認を整理します。

この記事の目次
  1. ファイル名は表示名ではなく登録IDに合わせる
  2. 最初の一文で変えるものと残すものを示す
  3. 入力表は型だけでなく単位と例外を書く
  4. 画像と動画は配布後のパスで確認する
  5. 配布用ZIPから入れてヘルプを開く

自作ノードの使い方を伝えるなら、READMEへのリンクだけでなく、ノードのヘルプから読める説明を同梱できます。ComfyUIはWEB_DIRECTORY内のMarkdownを読み、対応するノードの説明として表示します。実装の解説より、利用者が入力を選び、失敗を直せる情報を先に置きましょう。

ファイル名は表示名ではなく登録IDに合わせる

V1の公式手順では、NODE_CLASS_MAPPINGSのキーに合わせたMarkdownファイルを用意します。画面の読みやすい名前と、登録に使うIDが違う場合は取り違えないでください。

たとえば登録キーがDevsExampleNormalizeTextで、WEB_DIRECTORY = "./web"と設定したパックなら、次のように置きます。既存パックへ追加するときは、JavaScriptの配置を動かす必要はありません。

my-node-pack/
  __init__.py
  web/
    docs/
      DevsExampleNormalizeText.md
      DevsExampleNormalizeText/
        ja.md
        en.md

既定のMarkdownを残しておくと、用意していない言語へのフォールバックに使えます。日本語版だけを作って、他の言語で何も読めなくなる構成を避けます。V3パックでは使用する版の登録IDとの対応も確認し、表示名だけからパスを推測しないでください。

スポンサーリンク

最初の一文で変えるものと残すものを示す

「便利なテキスト処理」では、どの入力に使えばよいか分かりません。「前後の空白を取り除き、内部の改行は残す」のように、観察できる動作を書くと判断しやすくなります。続けて、一つの入力例と出力例を示します。

# テキストの前後の空白を取り除く

前後の空白を削除します。文章の中の改行は残します。

## 入力と出力
- text:整形する文字列
- 出力:整形後の文字列

## 例
入力:前後に空白がある「  blue sky  」
出力:「blue sky」

## 空の結果になったとき
入力が空白だけではないか確認してください。

これは架空のノードを説明する例です。実際のコードが内部の改行まで消すなら、説明もそれに合わせます。ヘルプのためだけに機能を増やすのではなく、実装の約束を短く表現します。

入力表は型だけでなく単位と例外を書く

ノードのソケットにFLOATと表示されていても、その数値が秒なのか、割合なのかは分かりません。値の範囲、単位、空欄の場合、他の入力との関係を必要な範囲で補います。

薄い説明 利用者が判断できる説明
strength:強度 0で変更なし、1で最大。対応範囲を明示
image:画像 RGB一枚かbatchか、透過を扱うか
path:パス 相対パスの基準と、読み取り/保存のどちらか

ノードに設定したtooltipだけで足りる単純な項目は、同じ文章を長く繰り返す必要がありません。長いヘルプには、組み合わせ条件や失敗例など、短い補足では伝わらない内容を置きます。

画像と動画は配布後のパスで確認する

Markdownでは画像や対応する動画要素も使えます。説明画像を付けるなら、自分の作業PCだけにある絶対パスを参照しないでください。配布物へ含め、インストールしたパックから表示できることを確認します。

作例には入力条件を添えます。特に生成モデルの結果を見せる場合、同じ結果を常に保証する表現にはしません。ヘルプを作っただけなら、実際の実行画面を確認したように書かず、図や説明用の例として扱います。

配布用ZIPから入れてヘルプを開く

作業フォルダーでは見えても、配布時の除外設定でdocsが落ちることがあります。利用者と同じ配布物から検証環境へ入れ、対象ノードのヘルプ、日本語と既定言語、画像の読み込みを確認します。変更した入力名と、ヘルプに残る旧名も照合してください。

2026年11月9日の公式ヘルプ作成手順を確認しています。利用者側の読み方はNode Docsの使い方、配布物の更新はRegistry公開の手順へつながります。最初は一つのノードに、入力例と代表的な失敗例を一つずつ付けるところから始められます。

スポンサーリンク