検索
サイト検索ダイアログを設定します。Tralume は静的ローカル検索用の pagefind と、ホスト型タイポトレラント検索用の meilisearch をサポートします。
サポートされるプロバイダー
| プロバイダー | バックエンド | 必須キー |
|---|---|---|
pagefind | 静的 Pagefind インデックス | テーマ設定では不要 |
meilisearch | セルフホストまたは Meilisearch Cloud | host, indexUid |
Pagefind
Pagefind はデフォルトのプロバイダーです:
[params.search]
# Note: Enables the search button and dialog.
enable = true
# Note: Loads /pagefind/<language>/pagefind.js generated by your Pagefind build step.
provider = 'pagefind'テーマは生成された Pagefind スクリプトを読み込むだけです。ビルドパイプラインで Pagefind インデックスをデプロイ先のサイト出力に生成する必要があります。
Meilisearch
ホスト型検索バックエンド、タイポトレランス、フィルター、ランキングルール、複数デプロイメント間での共有検索が必要な場合は Meilisearch を使用します。
[params.search]
# Note: Enables the search dialog.
enable = true
# Note: Switches the frontend provider to Meilisearch REST search.
provider = 'meilisearch'
[params.search.meilisearch]
# Note: Public Meilisearch endpoint, without a trailing slash.
host = 'https://search.example.com'
# Note: Use a Search API Key only. Never use the master key or admin key in frontend code.
apiKey = 'search-only-public-key'
# Note: Index UID containing the documents for the current site or language.
indexUid = 'tralume_posts_en'フロントエンドは POST /indexes/{index_uid}/search を呼び出します。Meilisearch JavaScript SDK や CDN スクリプトは不要です。
ドキュメント形状
デフォルトでは、Tralume は各 Meilisearch ドキュメントが以下のフィールドを公開することを期待します:
| フィールド | 目的 |
|---|---|
id | Meilisearch の主キー |
title | 検索結果のタイトル |
url | 結果リンク |
content | 切り抜き抜粋に使用されるメインテキスト |
summary または description | オプションのフォールバック抜粋 |
section | オプションの結果メタデータ |
異なるフィールド名をマッピングできます:
[params.search.meilisearch]
# Note: Maps the result title to your indexed field.
titleAttribute = 'headline'
# Note: Maps the result URL to your indexed field.
urlAttribute = 'permalink'
# Note: Maps small metadata shown below the result title.
metaAttribute = 'category'
# Note: Fields cropped by Meilisearch for excerpts.
excerptAttributes = ['body', 'summary']検索パラメータ
Tralume はダイアログで使用される一般的な Meilisearch 検索パラメータを公開します:
[params.search.meilisearch]
# Note: Maximum number of hits shown in the dialog.
limit = 20
# Note: Maximum words in each cropped excerpt returned by Meilisearch.
cropLength = 24
# Note: Restricts returned fields. These fields must be displayed attributes in Meilisearch.
attributesToRetrieve = ['title', 'url', 'content', 'section']
# Note: Restricts searchable fields. These fields must be searchable attributes in Meilisearch.
attributesToSearchOn = ['title', 'content']
# Note: Optional filter expression. Filtered fields must be filterable attributes in Meilisearch.
filter = 'lang = "en-US"'
# Note: Optional sort rules. Sorted fields must be sortable attributes in Meilisearch.
sort = ['date:desc']
# Note: Optional query matching strategy supported by Meilisearch.
matchingStrategy = 'last'
# Note: Optional highlight attributes. Matched terms in these fields are wrapped with <em> tags.
highlightAttributes = ['title', 'content']Meilisearch ではフィルターやソートルールが機能する前にインデックス設定が必要です。フィルター対象のすべてのフィールドを filterableAttributes に、ソート対象のすべてのフィールドを sortableAttributes に追加してください。
多言語サイト
多言語サイトの場合、言語ごとに1つのインデックスを使用するか、言語フィルター付きの共有インデックスを使用します。
[params.search.meilisearch]
# Note: Use a language-specific index when each Hugo language has its own params override.
indexUid = 'tralume_posts_en'[params.search.meilisearch]
# Note: Use a shared index and filter the current language if your documents contain lang.
indexUid = 'tralume_posts'
filter = 'lang = "en-US"'Meilisearch の locales を使用する場合は、Meilisearch がサポートする ISO 言語タグ（en や zh など）を渡します:
[params.search.meilisearch]
# Note: Helps Meilisearch choose the expected language analyzer for the query.
locales = ['en']セキュリティ
apiKey の値はブラウザに送信されます。必要なインデックスと search アクションに制限された Search API Key のみを使用してください。マスターキー、デフォルトの管理キー、またはドキュメントの書き込みや設定変更が可能なキーを決して公開しないでください。
# Note: Creates a narrowly scoped Search API Key for one index.
# Note: Run this on a trusted machine with your master key, not in browser code.
curl -X POST "${MEILISEARCH_URL}/keys" \
-H "Authorization: Bearer ${MEILISEARCH_MASTER_KEY}" \
-H "Content-Type: application/json" \
-d '{
"description": "Tralume frontend search",
"actions": ["search"],
"indexes": ["tralume_posts_en"],
"expiresAt": null
}'注意事項
- Tralume はフロントエンドのクエリ UI のみを実装します。Hugo コンテンツを Meilisearch にアップロードすることはありません。
- Meilisearch の
hostは、CORS またはリバースプロキシを通じてサイトオリジンからのブラウザリクエストを許可する必要があります。 apiKeyは、Meilisearch エンドポイントが意図的に公開されており認証がない場合にのみ省略できます。hostまたはindexUidが欠けている場合、ダイアログは通常の利用不可状態を表示します。