diff --git a/docs/assets/screenshots/search-highlighting.png b/docs/assets/screenshots/search-highlighting.png index 1560345b3..b8678cd3a 100644 Binary files a/docs/assets/screenshots/search-highlighting.png and b/docs/assets/screenshots/search-highlighting.png differ diff --git a/docs/assets/screenshots/search-suggestions.png b/docs/assets/screenshots/search-suggestions.png new file mode 100644 index 000000000..44191899a Binary files /dev/null and b/docs/assets/screenshots/search-suggestions.png differ diff --git a/docs/insiders.md b/docs/insiders.md index ffc8d2151..6dea5e383 100644 --- a/docs/insiders.md +++ b/docs/insiders.md @@ -61,27 +61,29 @@ for MkDocs Insiders. You can click on each feature to learn more about it: - [x] [Remove _Made with Material for MkDocs_ from footer][11] - [x] [Support for user-toggleable themes (light/dark mode switch)][12] -- [x] [Highlighting of matched search terms in content area][13] -- [x] [Navigation can always be expanded via configuration][14] -- [x] [Header can be automatically hidden on scrolling][15] -- [x] [Table of contents can be automatically hidden when empty][16] +- [x] [Search suggestions help to save keystrokes][13] +- [x] [Highlighting of matched search terms in content area][14] +- [x] [Navigation can always be expanded via configuration][15] +- [x] [Header can be automatically hidden on scrolling][16] +- [x] [Table of contents can be automatically hidden when empty][17] [11]: setup/setting-up-the-footer.md#remove-generator [12]: setup/changing-the-colors.md#color-palette-toggle - [13]: setup/setting-up-site-search.md#highlighting-search - [14]: setup/setting-up-navigation.md#navigation-expansion - [15]: setup/setting-up-the-header.md#automatic-hiding - [16]: setup/setting-up-navigation.md#automatic-hiding + [13]: setup/setting-up-site-search.md#search-suggestions + [14]: setup/setting-up-site-search.md#search-highlighting + [15]: setup/setting-up-navigation.md#navigation-expansion + [16]: setup/setting-up-the-header.md#automatic-hiding + [17]: setup/setting-up-navigation.md#automatic-hiding ## Roadmap The following list of funding goals – named after varieties of chili peppers -[I'm growing on my balcony][17] – shows which features are already available +[I'm growing on my balcony][18] – shows which features are already available in Material for MkDocs Insiders. - [17]: https://www.instagram.com/squidfunk/ + [18]: https://www.instagram.com/squidfunk/ -### Madame Jeanette :octicons-check-24: +### Madame Jeanette [:octicons-flame-24: Funding goal: __$500__][6] · :octicons-unlock-24: Status: _released_ @@ -95,10 +97,9 @@ in Material for MkDocs Insiders. [:octicons-flame-24: Funding goal: __$1,000__][6] · :octicons-lock-24: Status: _exclusive_ -- [x] [Highlighting of matched search terms in content area][13] -- [x] [Navigation can always be expanded via configuration][14] -- [x] [Header can be automatically hidden on scrolling][15] -- [x] [Table of contents can be automatically hidden when empty][16] +- [x] [Navigation can always be expanded via configuration][15] +- [x] [Header can be automatically hidden on scrolling][16] +- [x] [Table of contents can be automatically hidden when empty][17] - [ ] Table of contents can be moved into navigation for more space - [ ] Table of contents shows which sections have search results - [ ] Table of contents auto-collapses and expands only the active section @@ -126,7 +127,8 @@ in Material for MkDocs Insiders. [:octicons-flame-24: Funding goal: __$2,500__][6] · :octicons-lock-24: Status: _exclusive_ -- [ ] Support for search suggestions +- [x] [Search suggestions help to save keystrokes][13] +- [x] [Highlighting of matched search terms in content area][14] - [ ] Support for a user's last searches - [ ] Improved search result summaries diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 655edba0f..b6480a092 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -233,8 +233,11 @@ color palettes: This field is used as the toggle's `title` attribute and should be set to a discernable name to improve accessibility. -_Give this feature a try on [the official documentation][11] built with Material -for MkDocs Insiders!_ +[Try this feature][11]{: .md-button .md-button--primary } + +_This feature is enabled on the [official documentation][11] built with +Insiders. Click the button to go to Material for MkDocs Insiders and give this +feature a try._ [6]: ../insiders.md [7]: #color-scheme diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 5aa35ca76..7d5f1f3a8 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -130,7 +130,39 @@ them at your own risk._ [6]: changing-the-language.md#site-language [7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index -### Highlighting search +### Search suggestions + +[:octicons-file-code-24: Source][8] · +:octicons-unlock-24: Feature flag · +:octicons-beaker-24: Experimental · +[:octicons-heart-fill-24:{: .tx-heart } Insiders only][8]{: .tx-insiders } + +When _search suggestions_ are activated, the search will display the likeliest +completion for the last word, saving the user many key strokes by accepting the +suggestion with ++arrow-right++: + +``` yaml +theme: + features: + - search.suggest +``` + +Searching for [ :material-magnify: ^^code high^^ ] yields [ :material-magnify: +^^code highlighting^^ ] as a suggestion: + +[![Search suggestions][9]][9] + +[Try this feature][10]{: .md-button .md-button--primary } + +_This feature is enabled on the [official documentation][10] built with +Insiders. Click the button to go to Material for MkDocs Insiders and give this +feature a try._ + + [8]: ../insiders.md + [9]: ../assets/screenshots/search-suggestions.png + [10]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-site-search + +### Search highlighting [:octicons-file-code-24: Source][8] · :octicons-unlock-24: Feature flag · @@ -147,33 +179,35 @@ theme: - search.highlight ``` -Searching for `"code blocks"` yields: +Searching for [ :material-magnify: ^^code blocks^^ ] yields: -[![Search highlighting][9]][9] +[![Search highlighting][11]][11] -_Give this feature a try on [the official documentation][10] built with Material -for MkDocs Insiders!_ +[Try this feature][12]{: .md-button .md-button--primary } - [8]: ../insiders.md - [9]: ../assets/screenshots/search-highlighting.png - [10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks +_This feature is enabled on the [official documentation][12] built with +Insiders. Click the button to go to Material for MkDocs Insiders and give this +feature a try._ + + [11]: ../assets/screenshots/search-highlighting.png + [12]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks ### Offline search -[:octicons-file-code-24: Source][11] · -[:octicons-cpu-24: Plugin][12] · :octicons-beaker-24: Experimental +[:octicons-file-code-24: Source][13] · +[:octicons-cpu-24: Plugin][14] · :octicons-beaker-24: Experimental If you distribute your documentation as `*.html` files, the built-in search will not work out-of-the-box due to the restrictions modern browsers impose for -security reasons. This can be mitigated with the [localsearch][12] plugin in -combination with @squidfunk's [iframe-worker][13] polyfill. +security reasons. This can be mitigated with the [localsearch][14] plugin in +combination with @squidfunk's [iframe-worker][15] polyfill. -For setup instructions, refer to the [official documentation][14]. +For setup instructions, refer to the [official documentation][16]. - [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L360-L372 - [12]: https://github.com/wilhelmer/mkdocs-localsearch/ - [13]: https://github.com/squidfunk/iframe-worker - [14]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 + [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L360-L372 + [14]: https://github.com/wilhelmer/mkdocs-localsearch/ + [15]: https://github.com/squidfunk/iframe-worker + [16]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 ## Customization @@ -187,12 +221,12 @@ your needs. ### Query transformation -[:octicons-file-code-24: Source][15] · +[:octicons-file-code-24: Source][17] · :octicons-mortar-board-24: Difficulty: _easy_ When a user enters a query into the search box, the query is pre-processed before it is submitted to the search index. Material for MkDocs will apply the -following transformations, which can be customized by [extending the theme][16]: +following transformations, which can be customized by [extending the theme][18]: ``` ts /** @@ -232,7 +266,7 @@ export function defaultTransform(query: string): string { If you want to switch to the default behavior of the `mkdocs` or `readthedocs` template, both of which don't transform the query prior to submission, or customize the `transform` function, you can do this by [overriding the -`config` block][17]: +`config` block][19]: ``` html {% block config %} @@ -249,19 +283,19 @@ customize the `transform` function, you can do this by [overriding the The `transform` function will receive the query string as entered by the user and must return the processed query string to be submitted to the search index. - [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts - [16]: ../customization.md#extending-the-theme - [17]: ../customization.md#overriding-blocks + [17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts + [18]: ../customization.md#extending-the-theme + [19]: ../customization.md#overriding-blocks ### Custom search -[:octicons-file-code-24: Source][18] · +[:octicons-file-code-24: Source][20] · :octicons-mortar-board-24: Difficulty: _challenging_ -Material for MkDocs implements search as part of a [web worker][19]. If you +Material for MkDocs implements search as part of a [web worker][21]. If you want to switch the web worker with your own implementation, e.g. to submit search to an external service, you can add a custom JavaScript file to the `docs` -directory and [override the `config` block][17]: +directory and [override the `config` block][19]: ``` html {% block config %} @@ -278,8 +312,8 @@ message format using _discriminated unions_, i.e. through the `type` property of the message. See the following interface definitions to learn about the message formats: -* [:octicons-file-code-24: `SearchMessage`][20] -* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][21] +* [:octicons-file-code-24: `SearchMessage`][22] +* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][23] The sequence and direction of messages is rather intuitive: @@ -288,7 +322,7 @@ The sequence and direction of messages is rather intuitive: * :octicons-arrow-right-24: `SearchQueryMessage` * :octicons-arrow-left-24: `SearchResultMessage` - [18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker - [19]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers - [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts - [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts + [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker + [21]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers + [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts + [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts