Search

Configure the site search dialog. Tralume supports pagefind for static local search and meilisearch for hosted typo-tolerant search.

Supported providers

Provider	Backend	Required keys
`pagefind`	Static Pagefind index	none in theme config
`meilisearch`	Self-hosted or Meilisearch Cloud	`host`, `indexUid`

Pagefind

Pagefind is the default provider:

[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'

The theme only loads the generated Pagefind script. Your build pipeline must still generate the Pagefind index into the deployed site output.

Meilisearch

Use Meilisearch when you want a hosted search backend, typo tolerance, filters, ranking rules, or shared search across multiple deployments.

[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'

The frontend calls POST /indexes/{index_uid}/search. No Meilisearch JavaScript SDK or CDN script is required.

Document shape

By default, Tralume expects each Meilisearch document to expose these fields:

Field	Purpose
`id`	Primary key in Meilisearch
`title`	Search result title
`url`	Result link
`content`	Main text used for cropped excerpts
`summary` or `description`	Optional fallback excerpt
`section`	Optional result metadata

You can map different field names:

[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']

Search parameters

Tralume exposes the common Meilisearch search parameters used by the dialog:

[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 requires index settings before filters or sort rules can work. Add every filtered field to filterableAttributes, and every sorted field to sortableAttributes.

Multilingual sites

For multilingual sites, use either one index per language or one shared index with a language filter.

[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"'

If you use Meilisearch locales, pass ISO language tags supported by Meilisearch, such as en or zh:

[params.search.meilisearch]
  # Note: Helps Meilisearch choose the expected language analyzer for the query.
  locales = ['en']

Security

The apiKey value is shipped to the browser. Use only a Search API Key limited to the required index and search action. Never expose the master key, default admin key, or any key that can write documents or change settings.

# 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
  }'

Notes

Tralume implements the frontend query UI only. It does not upload Hugo content to Meilisearch.
Meilisearch host must allow browser requests from your site origin through CORS or a reverse proxy.
apiKey may be omitted only when your Meilisearch endpoint is intentionally public and unauthenticated.
Missing host or indexUid makes the dialog show the normal unavailable state.

Last updated on Jul 24, 2026 • alexma233

Analytics (Umami)Comments