身の回りの困りごとを楽しく解決！ by Works Human Intelligence Advent Calendar 2025

Obsidianで自作プラグイン作成シリーズ第一弾（Paste Image as WebP）

Last updated at 2025-11-30Posted at 2025-11-30

はじめに

Obsidianで画像を多用していると、Vaultのサイズがどんどん膨れ上がっていく経験はないでしょうか。特にスクリーンショットを頻繁に貼り付ける場合、PNGやJPEG形式の画像ファイルがストレージを圧迫します。

この問題を解決するため、クリップボードから画像をペーストする際に自動的にWebP形式に変換するObsidianプラグイン「Paste Image as WebP」を開発しました。本記事では、WebP形式の利点とプラグインの機能、そして開発の過程について解説します。

WebP形式の利点

WebPは、Googleが開発した画像フォーマットで、従来のPNGやJPEGと比較して以下のような優位性があります。

ファイルサイズの削減

WebPの最大の特徴は、高い圧縮率です。同程度の画質を保ちながら、PNGやJPEGと比較して20〜50%程度ファイルサイズを削減できます。

具体的な例を挙げると、4096×4096ピクセルのスクリーンショットの場合：

PNG形式：約8〜12MB
JPEG形式（品質85%）：約2〜4MB
WebP形式（品質85%）：約1〜2MB

この差は、画像を多用するVaultでは大きな影響を与えます。

透過対応

WebPは、PNG同様にアルファチャンネル（透過）をサポートしています。そのため、背景が透明な画像もそのまま扱うことができます。

ブラウザ対応

現在、主要なブラウザはすべてWebPをサポートしており、Obsidianでも問題なく表示できます。

プラグインの機能

基本機能

「Paste Image as WebP」プラグインは、以下の基本機能を提供します。

自動変換：クリップボードから画像をペースト（Ctrl+V / Cmd+V）すると、自動的にWebP形式に変換して保存
エディタへの自動挿入：変換後の画像を![[ファイル名.webp]]形式で自動的にエディタに挿入
重複ファイルの処理：同名ファイルが存在する場合、自動的に連番を追加（例：image-1.webp, image-2.webp）

ファイル名のカスタマイズ

ファイル名は2つの形式から選択できます。

固定名形式

同じファイル名で保存します。例えば、image.webpという固定名を設定すると、すべての画像がこの名前で保存されます（重複時は自動的に連番が追加されます）。

タイムスタンプ形式

日時をベースにしたファイル名を生成します。フォーマットは自由にカスタマイズ可能で、以下のプレースホルダーを使用できます。

YYYY：年（4桁）
MM：月（2桁）
DD：日（2桁）
HH：時（2桁、24時間形式）
mm：分（2桁）
ss：秒（2桁）

デフォルトのYYYYMMDDHHmmss形式では、20231116143025.webpのようなファイル名が生成されます。カスタム例として、YYYY-MM-DD_HHmmssとすると2023-11-16_143025.webpという形式になります。

保存先の設定

画像の保存先は3つのオプションから選択できます。

現在のノートと同じフォルダ：ノートと同じディレクトリに指定したフォルダ名（デフォルト：attachments）を作成して保存
Vaultルート：Vaultのルートに指定したフォルダを作成して保存
カスタムパス：任意のパスを指定（例：project/images）

WebP品質の調整

WebPの品質は0.1〜1.0の範囲で調整できます。デフォルトは0.85で、ファイルサイズと画質のバランスが取れた値です。

1.0：最高品質（ファイルサイズ大）
0.85：推奨値（バランス型）
0.5〜0.7：低品質（ファイルサイズ重視）

セキュリティ機能

プラグインには、以下のセキュリティ対策が実装されています。

パストラバーサル攻撃の防止：ファイル名とフォルダパスをサニタイズし、Vault外部への書き込みを防止
DoS攻撃の防止：画像の最大ピクセル数（デフォルト：16,777,216 = 4096×4096）と最大ファイルサイズ（デフォルト：10MB）を制限
ファイル名インジェクションの防止：特殊文字を適切に処理
無限ループの防止：重複ファイル名チェックの試行回数を制限

これらの設定は、プラグインの設定画面から変更できます。

技術的な実装

開発環境

プラグインは以下の技術スタックで開発しました。

言語：TypeScript
ビルドツール：esbuild
ターゲット環境：Obsidian Plugin API

プロジェクト構成

obsidian_extension/
├── main.ts              # メインのプラグインロジック
├── manifest.json        # プラグインのメタデータ
├── package.json         # npm設定
├── tsconfig.json        # TypeScript設定
├── esbuild.config.mjs   # esbuild設定
└── styles.css           # スタイルシート

TypeScriptからJavaScriptへのビルド

Obsidianプラグインは、最終的にJavaScriptファイル（main.js）として配布する必要があります。開発ではTypeScriptを使用し、esbuildでバンドル・トランスパイルしています。

package.jsonのスクリプト設定：

{
  "scripts": {
    "dev": "node esbuild.config.mjs",
    "build": "tsc -noEmit -skipLibCheck && node esbuild.config.mjs production"
  }
}

開発時はnpm run devでファイル変更を監視し、自動的にリビルドされます。本番ビルドはnpm run buildで実行します。

esbuildの設定

esbuildは高速なJavaScriptバンドラーで、TypeScriptのトランスパイルも行えます。設定ファイル（esbuild.config.mjs）では、以下を指定しています。

{
  entryPoints: ["main.ts"],
  bundle: true,
  external: ["obsidian", "electron", ...],
  format: "cjs",
  target: "es2018",
  outfile: "main.js"
}

重要なポイント：

external：Obsidianが提供するモジュールは外部依存として扱う
format: "cjs"：CommonJS形式で出力
target: "es2018"：ES2018をターゲットに設定

画像変換のコアロジック

画像の変換処理は、ブラウザのCanvas APIを使用しています。

private async convertToWebP(file: File): Promise<Blob> {
  return new Promise((resolve, reject) => {
    const img = new Image();
    const reader = new FileReader();

    reader.onload = (e) => {
      img.onload = () => {
        // 画像サイズの検証
        this.validateImageDimensions(img.width, img.height);

        // Canvasに描画
        const canvas = document.createElement('canvas');
        canvas.width = img.width;
        canvas.height = img.height;
        
        const ctx = canvas.getContext('2d');
        ctx.drawImage(img, 0, 0);

        // WebPに変換
        canvas.toBlob(
          (blob) => {
            if (blob) {
              resolve(blob);
            } else {
              reject(new Error('Failed to convert to WebP'));
            }
          },
          'image/webp',
          this.settings.webpQuality
        );
      };

      img.src = e.target?.result as string;
    };

    reader.readAsDataURL(file);
  });
}

この実装のポイント：

FileReaderでファイルをData URLとして読み込み
Image要素にロード
Canvasに描画
canvas.toBlob()でWebP形式に変換（品質指定可能）

ファイル保存処理

Obsidian Vault APIを使用してファイルを保存します。

private async saveImage(blob: Blob, filename: string, view: MarkdownView): Promise<string> {
  // フォルダパスの決定
  let folder: string;
  
  if (this.settings.imageFolderLocation === 'current-folder') {
    const currentFile = view.file;
    const baseFolder = currentFile?.parent?.path || '';
    folder = baseFolder ? `${baseFolder}/${folderName}` : folderName;
  }
  // ... その他のロケーション処理

  // フォルダが存在しない場合は作成
  const folderExists = await this.app.vault.adapter.exists(folder);
  if (!folderExists) {
    await this.app.vault.createFolder(folder);
  }

  // 重複チェックと保存
  let filepath = `${folder}/${filename}`;
  let counter = 1;
  
  while (await this.app.vault.adapter.exists(filepath)) {
    const nameWithoutExt = filename.replace('.webp', '');
    filepath = `${folder}/${nameWithoutExt}-${counter}.webp`;
    counter++;
  }

  // ArrayBufferに変換して保存
  const arrayBuffer = await blob.arrayBuffer();
  await this.app.vault.createBinary(filepath, arrayBuffer);

  return filepath;
}

クリップボードイベントのハンドリング

Obsidianのエディタペーストイベントをインターセプトします。

async onload() {
  await this.loadSettings();

  this.registerEvent(
    this.app.workspace.on('editor-paste', this.handlePaste.bind(this))
  );

  this.addSettingTab(new PasteImageAsWebPSettingTab(this.app, this));
}

private async handlePaste(evt: ClipboardEvent, editor: Editor, view: MarkdownView) {
  const files = evt.clipboardData?.files;
  if (!files || files.length === 0) {
    return; // 画像がない場合は通常のペースト処理
  }

  const imageFiles = Array.from(files).filter(file =>
    file.type.startsWith('image/')
  );

  if (imageFiles.length === 0) {
    return;
  }

  evt.preventDefault(); // デフォルトのペースト動作を防ぐ

  for (const file of imageFiles) {
    await this.processImage(file, editor, view);
  }
}

インストール方法

コミュニティプラグインから（現在リリース申請中です）

プルリクエストが通ったら、コミュニティプラグインからインストールできます。
今しばらくお待ちくださいませ (+_+)

手動インストール

GitHubリリースページからmain.js、manifest.json、styles.cssをダウンロード
Vaultのプラグインフォルダにpaste-image-as-webpフォルダを作成

ダウンロードしたファイルを配置
Obsidianを再起動してプラグインを有効化

使い方

プラグインを有効化
設定画面で好みに合わせてカスタマイズ
画像をクリップボードにコピー
Obsidianのエディタでペースト（Ctrl+V / Cmd+V）
自動的にWebP形式で保存され、エディタに挿入される

まとめ

「Paste Image as WebP」プラグインを使用することで、以下のメリットが得られます。

Vaultのサイズ削減：画像ファイルサイズが20〜50%削減され、ストレージを節約
シームレスな体験：通常のペースト操作と変わらない使い勝手
柔軟な設定：ファイル名、保存先、品質を自由にカスタマイズ可能
セキュリティ：各種攻撃に対する防御機能を実装

画像を多用するObsidianユーザーにとって、このプラグインはVault管理の負担を大きく軽減できるツールとなるはずです。

GitHubでオープンソースとして公開していますので、バグ報告や機能要望はIssuesでお待ちしています。

リンク

補足

基本的な使い方

1. プラグインの有効化

Obsidianの設定を開く（歯車アイコン）
左サイドバーから「コミュニティプラグイン」を選択
「Paste Image as WebP」を探して「有効化」をクリック

2. 画像の貼り付け手順

任意の画像をクリップボードにコピー
- スクリーンショットを撮る（Windows: Win + Shift + S、Mac: Cmd + Shift + 4）
- ブラウザや画像ビューアーで画像を右クリック→「コピー」
- 画像ファイルをコピー（Ctrl + C / Cmd + C）
Obsidianのエディタでペースト
- Ctrl + V（Windows/Linux）
- Cmd + V（Mac）
自動的に以下が実行される
- 画像がWebP形式に変換
- 指定したフォルダに保存
- エディタに![[ファイル名.webp]]形式で挿入
- 通知メッセージが表示される

設定項目の詳細

プラグインの設定画面は、「設定」→「コミュニティプラグイン」→「Paste Image as WebP」の歯車アイコンから開けます。

ファイル名設定（Filename format）

Filename format（ファイル名形式）

デフォルト値: Timestamp（タイムスタンプ）
選択肢:

Fixed name（固定名）：毎回同じファイル名で保存
Timestamp（タイムスタンプ）：日時ベースのファイル名
設定方法:
ドロップダウンメニューから選択します。

Fixed filename（固定ファイル名）

デフォルト値: image
適用条件: Filename formatが「Fixed name」の場合のみ表示
動作:

設定した名前で保存される（例：image.webp）
同名ファイルが存在する場合、自動的に連番が追加される
- 1枚目：image.webp
- 2枚目：image-1.webp
- 3枚目：image-2.webp
  設定方法:

Filename formatを「Fixed name」に変更
テキストフィールドに好きな名前を入力（拡張子は不要）
使用例:

設定値: screenshot
結果: screenshot.webp, screenshot-1.webp, screenshot-2.webp...

Timestamp format（タイムスタンプフォーマット）

デフォルト値: YYYYMMDDHHmmss
適用条件: Filename formatが「Timestamp」の場合のみ表示
使用可能なプレースホルダー:

YYYY：年（4桁）例：2024
MM：月（2桁）例：01, 12
DD：日（2桁）例：01, 31
HH：時（2桁、24時間形式）例：00, 23
mm：分（2桁）例：00, 59
ss：秒（2桁）例：00, 59
設定方法:

Filename formatを「Timestamp」に変更
テキストフィールドにフォーマットを入力
リアルタイムでサンプルが表示される
フォーマット例:
| フォーマット | 出力例 | 用途 |
|------------|--------|------|
| YYYYMMDDHHmmss | 20241130143025.webp | デフォルト、秒単位で一意 |
| YYYY-MM-DD_HHmmss | 2024-11-30_143025.webp | 読みやすい形式 |
| YYYYMMDD_HH-mm-ss | 20241130_14-30-25.webp | 時刻を区切る |
| YYYY-MM-DD | 2024-11-30.webp | 日付のみ（1日に1枚のみの場合） |
| YYYYMMDD-HHmm | 20241130-1430.webp | 分単位（秒は不要な場合） |
サンプル表示:
設定画面でフォーマットを入力すると、下部に現在時刻でのサンプルが表示されます。

Sample: 20241130143025.webp

保存先設定

Image folder location（画像フォルダの場所）

デフォルト値: Same folder as current note（現在のノートと同じフォルダ）
選択肢:

Same folder as current note：現在のノートと同じフォルダ
Vault root：Vaultのルート
Custom path：カスタムパス
設定方法:
ドロップダウンメニューから選択します。
各選択肢の動作:

1. Same folder as current note（推奨）

現在編集中のノートと同じフォルダに、指定したサブフォルダを作成して保存します。
例:

Vaultの構成:
├── Projects/
│   └── Project-A.md  ← 現在編集中
└── Daily/
    └── 2024-11-30.md
設定: Image folder name = "attachments"
保存先:
Projects/attachments/20241130143025.webp

メリット:

ノートと画像が近くに配置される
プロジェクトごとに画像を整理できる
ノートを移動しても相対パスが維持される

2. Vault root

Vaultのルートに、指定したフォルダを作成して保存します。
例:

Vaultの構成:
├── Projects/
│   └── Project-A.md  ← 現在編集中
└── attachments/      ← ここに保存される
    └── 20241130143025.webp

メリット:

すべての画像が1箇所に集約される
画像の一括管理が容易
デメリット:
ノート数が多いと画像フォルダが巨大になる

3. Custom path

任意のパスを指定して保存します。
例:

設定: Custom folder path = "resources/images"
保存先:
resources/images/20241130143025.webp

メリット:

完全に自由なフォルダ構造を実現
複数レベルのフォルダを指定可能

Image folder name（画像フォルダ名）

デフォルト値: attachments
適用条件: Image folder locationが「Custom path」以外の場合に表示
設定方法:
テキストフィールドにフォルダ名を入力します。
動作:

フォルダが存在しない場合、自動的に作成される
既存のフォルダがある場合、そこに保存される
例:

設定値: images
結果: 
- Same folder as current noteの場合: ノートのフォルダ/images/
- Vault rootの場合: Vaultルート/images/

Custom folder path（カスタムフォルダパス）

デフォルト値: project/images
適用条件: Image folder locationが「Custom path」の場合のみ表示
設定方法:

Image folder locationを「Custom path」に変更
テキストフィールドに完全なパスを入力
パス指定の規則:

Vaultルートからの相対パス
/（スラッシュ）で区切る
先頭や末尾のスラッシュは不要
例:

設定値: resources/screenshots
結果: Vaultルート/resources/screenshots/
設定値: work/projects/project-a/assets
結果: Vaultルート/work/projects/project-a/assets/

サンプル表示:
設定画面の下部に保存先のプレビューが表示されます。

Images will be saved to: project/images/

画質設定

Image quality (WebP)（画像品質）

デフォルト値: 0.85
範囲: 0.1〜1.0（スライダーで調整、0.05刻み）
説明:

1.0：最高品質（ファイルサイズが最大）
0.85：推奨値（品質とサイズのバランス）
0.5〜0.7：低品質（ファイルサイズ重視）
設定方法:
スライダーをドラッグして調整します。リアルタイムで値が表示されます。
品質とファイルサイズの目安:

品質設定	ファイルサイズ	画質	推奨用途
1.0	100%	最高	写真の保管、印刷用
0.9	約80%	非常に高い	高品質が必要な画像
0.85	約70%	高い	一般的な用途（推奨）
0.8	約60%	高い	スクリーンショット
0.7	約50%	中程度	図表、ダイアグラム
0.5	約30%	低い	サムネイル、下書き
実例（1920×1080のスクリーンショット）:

PNG形式: 約2.5MB
品質1.0: 約1.5MB（40%削減）
品質0.85: 約800KB（68%削減）← デフォルト
品質0.7: 約500KB（80%削減）

セキュリティ設定

Maximum image size（最大画像サイズ）

デフォルト値: 16777216（ピクセル）
説明:
画像の最大ピクセル数（幅 × 高さ）を制限します。
計算例:

16,777,216ピクセル = 4096 × 4096
4,194,304ピクセル = 2048 × 2048
67,108,864ピクセル = 8192 × 8192
設定方法:
テキストフィールドに数値を入力します。
推奨値:

用途	推奨値	サイズ例
一般的な用途	16,777,216	4096×4096
高セキュリティ環境	4,194,304	2048×2048
パワーユーザー	67,108,864	8192×8192
目的:
巨大な画像によるメモリ枯渇（DoS攻撃）を防ぎます。
エラー時の挙動:
制限を超える画像をペーストすると、エラーメッセージが表示され、画像は保存されません。

Image dimensions exceed maximum allowed size

Maximum file size (MB)（最大ファイルサイズ）

デフォルト値: 10 MB
説明:
ペースト可能な画像ファイルの最大サイズをMB単位で制限します。
設定方法:
テキストフィールドに数値を入力します（小数点も使用可能）。
推奨値:

用途	推奨値
一般的な用途	10 MB
高セキュリティ環境	5 MB
パワーユーザー	50 MB
例:

設定値: 5
結果: 5MB以下の画像のみペースト可能
設定値: 2.5
結果: 2.5MB以下の画像のみペースト可能

エラー時の挙動:
制限を超える画像をペーストすると、エラーメッセージが表示されます。

Image file size exceeds 10MB limit

実践的な設定例

例1: 日記用の設定（デフォルト推奨）

Filename format: Timestamp
Timestamp format: YYYYMMDDHHmmss
Image folder location: Same folder as current note
Image folder name: attachments
Image quality: 0.85
Maximum image size: 16777216
Maximum file size: 10 MB

動作:

Vaultの構成:
├── Daily/
│   ├── 2024-11-30.md  ← 編集中
│   └── attachments/
│       └── 20241130143025.webp  ← 保存される

例2: プロジェクト管理用の設定

Filename format: Fixed name
Fixed filename: screenshot
Image folder location: Same folder as current note
Image folder name: images
Image quality: 0.8
Maximum image size: 16777216
Maximum file size: 10 MB

動作:

Vaultの構成:
├── Projects/
│   ├── ProjectA/
│   │   ├── overview.md  ← 編集中
│   │   └── images/
│   │       ├── screenshot.webp
│   │       ├── screenshot-1.webp
│   │       └── screenshot-2.webp

例3: 一元管理用の設定

Filename format: Timestamp
Timestamp format: YYYY-MM-DD_HHmmss
Image folder location: Vault root
Image folder name: assets
Image quality: 0.85
Maximum image size: 16777216
Maximum file size: 10 MB

動作:

Vaultの構成:
├── assets/
│   ├── 2024-11-30_143025.webp
│   ├── 2024-11-30_150312.webp
│   └── 2024-11-30_163540.webp
├── Projects/
│   └── overview.md  ← どこから貼っても assets/ に保存
└── Daily/
    └── 2024-11-30.md

例4: 高品質写真保存用

Filename format: Timestamp
Timestamp format: YYYY-MM-DD_HHmmss
Image folder location: Custom path
Custom folder path: media/photos
Image quality: 0.95
Maximum image size: 67108864
Maximum file size: 50 MB

用途: 写真をアーカイブとして保存する場合

トラブルシューティング

画像がペーストされない

確認事項:

プラグインが有効化されているか
クリップボードに画像データがあるか
ファイルサイズや画像サイズが制限内か
対処法:

コンソール（Ctrl + Shift + I）でエラーを確認
セキュリティ設定の制限を一時的に緩和して確認

フォルダが作成されない

原因:
親フォルダが存在しない場合、自動作成されません。
対処法:

手動で親フォルダを作成
または、シンプルなフォルダ構造に変更
例:

設定: Custom folder path = "projects/work/screenshots"
親フォルダ "projects/work" が存在しない場合 → エラー
対処: 先に "projects/work" フォルダを手動で作成

同名ファイルが増え続ける

原因:
Fixed name形式で連番が増え続けている。
対処法:

Timestamp形式に変更
または、定期的に古い画像を整理

まとめ

「Paste Image as WebP」プラグインの設定は、用途に応じて柔軟にカスタマイズできます。

推奨設定:

一般ユーザー：デフォルト設定のまま
こだわり派：Timestamp formatを読みやすい形式に
大量の画像を扱う：品質を0.7〜0.8に下げてファイルサイズを削減
自分の使い方に合わせて、最適な設定を見つけてください。

謝辞

ClaudeCode 様にはペアプロを嫌な顔せずしていただきました。
nanobanana pro 様には図解を作る際に大変お世話になりました。
いつもいつもありがとうございます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Obsidianで自作プラグイン作成シリーズ 第一弾（Paste Image as WebP）

はじめに

WebP形式の利点

ファイルサイズの削減

透過対応

ブラウザ対応

プラグインの機能

基本機能

ファイル名のカスタマイズ

固定名形式

タイムスタンプ形式

保存先の設定

WebP品質の調整

セキュリティ機能

技術的な実装

開発環境

プロジェクト構成

TypeScriptからJavaScriptへのビルド

esbuildの設定

画像変換のコアロジック

ファイル保存処理

クリップボードイベントのハンドリング

インストール方法

コミュニティプラグインから（現在リリース申請中です）

手動インストール

使い方

まとめ

リンク

補足

基本的な使い方

1. プラグインの有効化

2. 画像の貼り付け手順

設定項目の詳細

ファイル名設定（Filename format）

Filename format（ファイル名形式）

Fixed filename（固定ファイル名）

Timestamp format（タイムスタンプフォーマット）

保存先設定

Image folder location（画像フォルダの場所）

1. Same folder as current note（推奨）

2. Vault root

3. Custom path

Image folder name（画像フォルダ名）

Custom folder path（カスタムフォルダパス）

画質設定

Image quality (WebP)（画像品質）

セキュリティ設定

Maximum image size（最大画像サイズ）

Maximum file size (MB)（最大ファイルサイズ）

実践的な設定例

例1: 日記用の設定（デフォルト推奨）

例2: プロジェクト管理用の設定

例3: 一元管理用の設定

例4: 高品質写真保存用

用途: 写真をアーカイブとして保存する場合

トラブルシューティング

画像がペーストされない

フォルダが作成されない

同名ファイルが増え続ける

まとめ

謝辞

Obsidianで自作プラグイン作成シリーズ第一弾（Paste Image as WebP）