Allow adjusting search boost for title and tags fields

[ekoleda-codaio]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

Allow developers to adjust the search boost that comes from a search term matching the title or tags of a page. Currently these are hardcoded at 1e3 and 1e6 respectively.

mkdocs-material/src/assets/javascripts/integrations/search/_/index.ts

Lines 204 to 213 in ed6f0b1

	/* Set up fields */
	this.field("title", { boost: 1e3 })
	this.field("text")
	this.field("tags", { boost: 1e6, extractor: doc => {
	const { tags = [] } = doc as SearchDocument
	return tags.reduce((list, tag) => [
	...list,
	...lunr.tokenizer(tag)
	], [] as lunr.Token[])
	} })

Use Cases

You can tune search results with search boosting, and the page recommends starting with low values. However if you are trying to boost a page above another that has an exact match in the title, your boost must be greater than 1e3, which is quite huge. Allowing developer to adjust these constants would make it easier to tune search.

Screenshots / Mockups

Add entries somewhere in mkdocs.yml, perhaps under theme.

[squidfunk]

Thanks for suggesting. Additional to boosts, there are some other parameters that we can expose to tune search, which is an excellent addition to the built-in search plugin. I'll cook something up in the coming weeks.

[squidfunk]

I'll be revisiting this feature request shortly, as soon as beta 9 reaches a stable status and is released 😊 The reason why this takes some time is that the search was refactored and that first needs to be merged back into Insiders, so efforts are not duplicated. I'm sorry for the inconvenience, but it'll be worth the wait, as I'm planning other new interesting features for search that are made possible by the refactoring, including the things that were asked in this issue.

[ekoleda-codaio]

Thanks for the update. I found a weighting that counteracts these built in boosts well enough for now, so this isn't urgent.

[squidfunk]

bde0f4f63 adds support for customizable field boosts. I still need to update the documentation, but this is now possible:

plugins:
  - search:
      fields:
        title:
          boost: 0.5 # Current default: 1e3
        tags:
          boost: 2.0 # Current default: 1e6

Note that values currently need to be floats, so 2 will not work, but 2.0 will. This is the beginning of the next iteration on the search plugin, which will bring powerful customization possibilities, so the implementation is still work in progress.

[ekoleda-codaio]

Exciting, thanks! Anyway you could automatically cast the numbers to floats? I feel like that's something I'll forget when using this feature.

[squidfunk]

Absolutely agree, but I'm still fighting MkDocs config validation format 😅 Haven't found a way yet to use a union (int | float), but wanted your feedback nonetheless.

[squidfunk]

Fixed in 1999599 – you can now use integers or floats. This feature has been part of Insiders for some time now, but it's still inofficial, because it is only the beginning of field-level configuration. We won't add documentation at this point. You can use this feature as described in #4512 (comment). Later this year, search will get new functionality.

[squidfunk]

Released as part of 9.0.13+insiders-4.31.0.