[reakaleek]

Why

• In the Explore APIs search, ml flush and flush ml return nothing and flush ML job ranks the ML flush job operation below 90 others, while _ml _flush finds it first. The search analyzer keeps _ml, _flush and ml-flush-job as single tokens, and the ml => machine learning synonym fires on the query side only, so the typed words never meet the indexed ones.
• Every indexed API operation had an empty headings array although the spec tags each one, so the index held no group data, and search results showed no group in their breadcrumb although the operation page does.

Part of elastic/docs-eng-team#1141 (search matching and the group in the result breadcrumb; the deprecated badge on results and the endpoint paths on the landing page follow in separate PRs).

What

• Append the tag display name and the plain words of the operation id and path to each operation's search_title, so ml flush, flush ml, flush ML job, ml flush job and _ml _flush all find POST /_ml/anomaly_detectors/{job_id}/_flush. The query builder is unchanged.
• Index the operation's group as a third parent, with the tag page as its link, so the result breadcrumb reads API / Elasticsearch API / Machine learning anomaly detection like the page does. The breadcrumb formatter now labels only the product crumb.
• Keep the tag names in headings and add api.deprecated to the indexed operation metadata for the badge follow-up.

Notes

• The indexer re-parsed the generated API body with plain Markdig and replaced headings with its heading blocks, which never carry the header data, so the array was always empty. The fix keeps the exporter's tag names instead. One resolver in OpenApiExtensionReader now serves navigation and the index, and the group parent uses the same tag page moniker as the sidebar, which already fails the build on a slug collision.

• Verified on the dev index by re-running assembler index --environment dev and the relevance suite. In the API filter, before and after:

  Query	Before	After
  ml flush, flush ml	0 hits	ML flush job first
  flush ML job, ml flush job	not in the top 8 of 90	ML flush job first
  _ml _flush	ML flush job first	unchanged
  flush	indices flush first	unchanged

  Docs-wide first results for ml, machine learning, aliases, templates and indices are unchanged. The relevance suite's failures on the new index are a strict subset of those on the previous index (13 of 54, down from 21); the eight that now pass are the four flush cases, _search in three spellings and cloud. The running site shows the three-crumb breadcrumb on every tagged result.

• The api mapping changes (deprecated added), so the first index run after deploy rolls the indices over (about six minutes on dev).

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4666/

Sample changed pages:

• docs/data/openapi/api-explorer.md

[reakaleek]

LGTM