Obsidianで検索・置換を実現するプラグインを開発した

Posted at 2026-01-19

はじめに

Obsidianで大量のノートを管理していると、複数のファイルにわたって一括で文字列を置換したい場面に遭遇することはないでしょうか。例えば、

プロジェクト名の変更
リンク形式の統一
タグの整理など、、

手作業では時間がかかり、ミスも発生しやすい作業です。
当然、obsidianはノートアプリなので、検索と置換をしようと思ったのですが、、、

まさかの、置換ができなかった！！

自分が見つけれてないだけで、obsidian文字列の置換ができるよーって知っている方は教えてください。ちなみに、Obsidian標準の検索機能は強力ですが、なぜか置換だけがありません。。

この課題を解決するため、Vault全体を対象とした高度な検索・置換機能を提供するプラグイン
「Editor Essentials」を開発しました。
本記事では、プラグインの機能と使い方、そして開発過程で得た知見について解説します。

プラグインの特徴

主要機能

「Editor Essentials」プラグインは、以下の機能を提供します。

Vault全体の検索：すべてのノートを対象に、指定した文字列またはパターンを検索
正規表現サポート：複雑なパターンマッチングによる高度な検索
プレビュー機能：置換前に全マッチを確認
選択的な置換：各マッチにチェックボックスを配置し、個別に置換可否を選択
ファイルごとのグループ表示：検索結果をファイル別に整理して表示
行番号表示：マッチ箇所の位置を正確に把握

技術的な実装

開発環境

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

言語: TypeScript
ビルドツール: esbuild
ターゲット環境: Obsidian Plugin API
スタイリング: CSS（Obsidianネイティブ変数使用）

プロジェクト構成

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

コアロジック: 検索処理

Vault全体のファイルを走査し、パターンにマッチする箇所を抽出します。

async performSearch(searchText: string, useRegex: boolean, caseSensitive: boolean) {
  const files = this.app.vault.getMarkdownFiles();
  const results = new Map<string, SearchResult[]>();
  for (const file of files) {
    const content = await this.app.vault.read(file);
    const lines = content.split('\n');
    const fileResults: SearchResult[] = [];
    let pattern: RegExp;
    if (useRegex) {
      const flags = caseSensitive ? 'g' : 'gi';
      pattern = new RegExp(searchText, flags);
    } else {
      const escaped = searchText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
      const flags = caseSensitive ? 'g' : 'gi';
      pattern = new RegExp(escaped, flags);
    }
    lines.forEach((line, index) => {
      let match;
      while ((match = pattern.exec(line)) !== null) {
        fileResults.push({
          line: index + 1,
          text: line,
          matchStart: match.index,
          matchEnd: match.index + match[0].length,
          selected: true // デフォルトで選択状態
        });
      }
    });
    if (fileResults.length > 0) {
      results.set(file.path, fileResults);
    }
  }
  return results;
}

ハイライト表示の実装

マッチ箇所を<mark>タグで囲み、視覚的に強調表示します。

private highlightMatch(text: string, matchStart: number, matchEnd: number): string {
  const before = text.substring(0, matchStart);
  const match = text.substring(matchStart, matchEnd);
  const after = text.substring(matchEnd);
  return `${this.escapeHtml(before)}<mark>${this.escapeHtml(match)}</mark>${this.escapeHtml(after)}`;
}
private escapeHtml(text: string): string {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

置換処理

選択されたマッチのみを対象に、ファイルを更新します。

async performReplace(
  results: Map<string, SearchResult[]>,
  searchText: string,
  replaceText: string,
  useRegex: boolean,
  caseSensitive: boolean
) {
  let totalReplaced = 0;
  for (const [filePath, fileResults] of results) {
    const selectedResults = fileResults.filter(r => r.selected);
    if (selectedResults.length === 0) continue;
    const file = this.app.vault.getAbstractFileByPath(filePath);
    if (!(file instanceof TFile)) continue;
    let content = await this.app.vault.read(file);
    const lines = content.split('\n');
    // 行番号の降順でソート（後ろから処理することで位置がずれない）
    selectedResults.sort((a, b) => b.line - a.line);
    for (const result of selectedResults) {
      const lineIndex = result.line - 1;
      const line = lines[lineIndex];
      let pattern: RegExp;
      if (useRegex) {
        const flags = caseSensitive ? 'g' : 'gi';
        pattern = new RegExp(searchText, flags);
      } else {
        const escaped = searchText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
        const flags = caseSensitive ? 'g' : 'gi';
        pattern = new RegExp(escaped, flags);
      }
      lines[lineIndex] = line.replace(pattern, replaceText);
      totalReplaced++;
    }
    const newContent = lines.join('\n');
    await this.app.vault.modify(file, newContent);
  }
  return totalReplaced;
}

UIの動的生成

検索結果を表示するDOMを動的に生成します。

private renderResults(results: Map<string, SearchResult[]>) {
  const container = this.containerEl.querySelector('.ee-search-results');
  container.empty();
  if (results.size === 0) {
    container.createEl('div', {
      cls: 'ee-no-results',
      text: '一致する結果が見つかりませんでした'
    });
    return;
  }
  // サマリー情報
  const totalMatches = Array.from(results.values())
    .reduce((sum, arr) => sum + arr.length, 0);
  container.createEl('div', {
    cls: 'ee-search-info',
    text: `${results.size}個のファイルで${totalMatches}件のマッチが見つかりました`
  });
  // ファイルごとの結果
  for (const [filePath, fileResults] of results) {
    const fileGroup = container.createEl('div', { cls: 'ee-file-result' });
    // ファイルヘッダー
    const header = fileGroup.createEl('div', {
      cls: 'ee-file-header',
      text: `📄 ${filePath} (${fileResults.length}件)`
    });
    header.addEventListener('click', () => {
      matchContainer.toggleClass('is-collapsed', !matchContainer.hasClass('is-collapsed'));
    });
    // マッチアイテム
    const matchContainer = fileGroup.createEl('div', { cls: 'ee-match-container' });
    fileResults.forEach((result, index) => {
      const matchItem = matchContainer.createEl('div', { cls: 'ee-match-item' });
      // チェックボックス
      const checkbox = matchItem.createEl('input', { type: 'checkbox' });
      checkbox.checked = result.selected;
      checkbox.addEventListener('change', () => {
        result.selected = checkbox.checked;
      });
      // 行番号
      matchItem.createEl('span', {
        cls: 'ee-line-num',
        text: result.line.toString()
      });
      // マッチテキスト
      const textEl = matchItem.createEl('span', { cls: 'ee-match-text' });
      textEl.innerHTML = this.highlightMatch(
        result.text,
        result.matchStart,
        result.matchEnd
      );
      // クリックでファイルを開く
      textEl.addEventListener('click', () => {
        this.openFileAtLine(filePath, result.line);
      });
    });
  }
}

ファイルを特定行で開く

マッチをクリックすると、該当ファイルの該当行にジャンプします。

private async openFileAtLine(filePath: string, line: number) {
  const file = this.app.vault.getAbstractFileByPath(filePath);
  if (!(file instanceof TFile)) return;
  const leaf = this.app.workspace.getLeaf(false);
  await leaf.openFile(file);
  const view = leaf.view;
  if (view instanceof MarkdownView) {
    const editor = view.editor;
    const lineStart = { line: line - 1, ch: 0 };
    editor.setCursor(lineStart);
    editor.scrollIntoView({
      from: lineStart,
      to: lineStart
    }, true);
  }
}

正規表現のバリデーション

無効な正規表現が入力された場合、適切なエラー処理を行います。

private validateRegex(pattern: string): boolean {
  try {
    new RegExp(pattern);
    return true;
  } catch (e) {
    new Notice('無効な正規表現です: ' + e.message);
    return false;
  }
}

開発で得た知見

1. パフォーマンスの最適化

大規模なVaultでは、検索処理に時間がかかる可能性があります。以下の最適化を実装しました。

非同期処理: async/awaitを使用してUIをブロックしない
プログレス表示: 大量のファイルを処理する際の進捗表示
インクリメンタル検索: 入力のデバウンス処理

private debounceSearch = debounce(
  async (searchText: string) => {
    if (searchText.length < 2) return; // 最小2文字
    await this.performSearch(searchText, this.useRegex, this.caseSensitive);
  },
  500 // 500ms待機
);

2. メモリ管理

検索結果を適切に管理し、メモリリークを防ぎます。

async onunload() {
  // 結果をクリア
  this.searchResults.clear();
  // イベントリスナーを解除
  this.containerEl.empty();
}

3. エラーハンドリング

ファイル読み込みや書き込みの失敗に対応します。

try {
  const content = await this.app.vault.read(file);
  // 処理
} catch (error) {
  console.error(`Failed to read file ${file.path}:`, error);
  new Notice(`ファイルの読み込みに失敗しました: ${file.path}`);
}