Search failures at https://www.eclipse.org/openj9/docs/

[gjdeval]

When searching to see whether OpenJ9 supports some JVM arg, the search box at the top of the page often fails, reporting "No matching documents" even when the arg is in fact supported and documented.

A recent example is -XX:ParallelGCThread
Searching with the full value shows "No matching documents", which does not change if I remove the "-" or remove "-XX:"

But if I start with just "Parallel" in the search box (no quotes), then '-XX:ParallelGCThread' is shown as a choice, among other JVM args containing the string 'parallel'.

[doveye]

Search does seem a bit random. For example, "codecache" finds -XX:[+|-]PrintCodeCache but not -XX:codecachetotal. The MkDocs software levels need updating, which might make a difference. Looks like some search index options were added last June: https://www.mkdocs.org/about/release-notes/.

[doveye]

The MkDocs levels have just been updated but this problem still exists. Needs more investigation. For example, looks like the colon (:) was until just a few days ago replaced by whitespace during a search: squidfunk/mkdocs-material#4884.

[HonkingGoose]

You can customize the search by using the separator ¹ property in your mkdocs.yml config file.

For example, here's what Material for MkDocs uses for their docs site:

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

And here's the config ² we used to improve search on our Renovate docs site:

plugins:
  - search:
      separator: '[\s\-,:!?=\[\]()<>{}"/\\]+|\.(?!\d)|&[lg]t;'

Before you apply any of these configs, read the Material for MkDocs manual, and get help from somebody who knows their regex. 😉

Footnotes

1. https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.separator ↩

2. https://github.com/renovatebot/renovatebot.github.io/blob/22a3c58b1c0a4a8d1a7cadc3d3b31cb33c897cb8/mkdocs.yml#L177-L179 ↩

[doveye]

Thanks for the tips @HonkingGoose 🙂

[HonkingGoose]

The Material for MkDocs maintainer is working on better search, see this issue:

• Towards better documentation search  squidfunk/mkdocs-material#6307

There's also a PR with the new search as preview on that repository.