Search tuning

Search tuning

search.yaml corrects your site search where your readers and your writers use different words.

The four controls

synonyms:
  - [cancel, unsubscribe, close account]
  - [token, api key, credential]

aliases:
  sso: /team/sso
  pricing: /plans/tiers

pinned:
  publish:
    - /publish/publishing
    - /start/quickstart

boost:
  /start/quickstart: 2.0
  /trust/privacy: 0.5

Synonyms

A list of lists. Every word in a group matches every other. Use this when your readers say something your documentation does not.

Take the groups from your own no-result searches rather than from a thesaurus. The queries that found nothing are the exact list of words your documentation is missing.

Aliases

A query that should go straight to one page. sso sends the reader to /team/sso rather than to a ranked list.

Use an alias for a query with one right answer. A query with three plausible answers should be ranked, not aliased.

Pinned

Results forced to the top for a query, in the order you list them. Everything else is ranked below.

Boost

A weight per page. Above 1.0 lifts a page in every query it matches; below 1.0 pushes it down.

Boost is the blunt control. Use it for a landing page that should outrank the deep page it links to, and for a reference page that keeps outranking the guide.

Rules

Rule	Severity	What it means
search-invalid	warning	The YAML does not match the schema.
search-missing-page	warning	An alias, pin or boost names a page that does not exist.

Both are warnings because search still works without the tuning. A file that cannot be parsed is caught and ignored so that a broken tuning file cannot break search itself.

Danger

search.yaml is YAML, not prose. Do not paste it into a Markdown editor that reformats content. The writer opens site files as YAML for this reason.