Docusaurus Search with DuckDB Example

DuckDB WASMを使用してブラウザ内で高速な全文検索を実現するDocusaurusプラグインの実装例です。

デモサイトを用意してあります。

https://route06.github.io/docusaurus-search-with-duckdb-example/search/

よろしければ、下記ブログ記事もご覧ください。

• Docusaurus v3 の全文検索を DuckDB Wasm + FTS 拡張で実装した - ROUTE06 Tech Blog

Note

本件実装前に作成した PoC 版のコードが poc/ にあります。全文検索の他に、「日本語全文検索（わかち書き版）」と「ベクトル検索」もあります。

特徴

• ブラウザ内検索: DuckDB WASMを使用してサーバー不要の全文検索
• 高速検索: BM25スコアリングによる関連度ベースの検索結果
• SQLデバッグ: 開発者向けのSQL実行デバッグ機能
• リアルタイム: ページ遷移なしでの検索結果表示

技術スタック

• Docusaurus 3.4.0 - 静的サイトジェネレータ
• DuckDB WASM - ブラウザ内SQLデータベース
• React 18 + TypeScript - UIフレームワーク
• FTS (Full-Text Search) - 全文検索機能

動作方法

前提条件

• Node.js 22.16.0

セットアップ

依存関係のインストール：

yarn

動作方法

開発サーバー起動：

yarn start

プロダクション用動作確認：

# プロダクションビルド
yarn build

# ビルド済みサイトをローカルで確認
yarn serve

アーキテクチャ

データフロー

1. ドキュメント収集: collect-docs.jsがdocs/とblog/のマークダウンファイルを収集
2. データ変換: マークダウンをパースしてプレーンテキストに変換
3. JSON出力: static/docs.jsonとして構造化データを生成
4. ブラウザロード: DuckDB WASMがdocs.jsonをロードしてFTSインデックスを作成
5. 検索実行: BM25アルゴリズムによる関連度スコアベースの検索

プラグイン構成

plugins/docusaurus-search-duckdb/
├── index.js                 # メインプラグインエントリ
├── scripts/
│   └── collect-docs.js      # ドキュメント収集スクリプト
└── src/
    ├── components/          # UIコンポーネント
    ├── theme/              # テーマコンポーネント
    ├── utils/              # ユーティリティ関数
    └── types/              # TypeScript型定義

カスタマイズ

プラグイン設定

docusaurus.config.jsで設定をカスタマイズできます：

plugins: [
  [
    "./plugins/docusaurus-search-duckdb",
    {
      routeBasePath: "/search",     // 検索ページのパス
      docsJsonPath: "docs.json",    // ドキュメントJSONファイルのパス
      enableDebugMode: true,        // SQLデバッグ機能の有効/無効
    },
  ],
],

対象ディレクトリの変更

環境変数TARGET_DIRSで収集対象ディレクトリを指定：

TARGET_DIRS="docs,blog,custom" yarn start

ライセンス

Apache-2.0