diff --git a/docs/insiders.md b/docs/insiders.md index fbb163be9..3e2074a22 100644 --- a/docs/insiders.md +++ b/docs/insiders.md @@ -32,8 +32,8 @@ tied to it are merged back into Material for MkDocs and released for general availability. Bugfixes will always be released simultaneously in both editions. See the [roadmap][4] for a list of already available and upcoming features, and -for demonstration purposes, [the official docs][5] built with Material for -MkDocs Insiders. +for demonstration purposes, [the official documentation][5] built with Material +for MkDocs Insiders. [4]: #roadmap [5]: https://squidfunk.github.io/mkdocs-material-insiders/ @@ -75,7 +75,7 @@ in Material for MkDocs Insiders. ### Madame Jeanette [:octicons-fire-24: Funding goal: __$500__][6] · -:octicons-lock-24: Status: _exclusively available_ +:octicons-lock-24: Status: _exclusive_ New features and improvements for _search_, including: @@ -88,11 +88,11 @@ New features and improvements for _search_, including: ### Prairie Fire [:octicons-fire-24: Funding goal: __$1,000__][6] · -:octicons-lock-24: Status: _pending_ +:octicons-lock-24: Status: _exclusive_ New features and improvements for _content and toc_, including: -- [ ] Highlighting of matched search terms in content area +- [x] Highlighting of matched search terms in content area - [ ] Better support for wide screens, i.e. more horizontal space - [ ] Table of contents can be moved into navigation for more space - [ ] Table of contents shows which sections have search results diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index 514153b34..be5d40d30 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -17,10 +17,10 @@ made available [offline][1]. [:octicons-file-code-24: Source][2] · [:octicons-cpu-24: Plugin][3] · -[:octicons-heart-fill-24:{: .tx-heart } Insiders: new search UI/UX](../insiders.md){: .tx-insiders } +[:octicons-heart-fill-24:{: .tx-heart } Insiders – improved user experience][4]{: .tx-insiders } The [built-in search plugin][3] integrates seamlessly with Material for MkDocs, -adding multilingual client-side search with [lunr][4] and [lunr-languages][5]. +adding multilingual client-side search with [lunr][5] and [lunr-languages][6]. It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins are used: @@ -34,9 +34,9 @@ The following options are supported: `lang`{: #lang } : :octicons-milestone-24: Default: _automatically set_ – This option allows - to include the language-specific stemmers provided by [lunr-languages][5]. + to include the language-specific stemmers provided by [lunr-languages][6]. Note that Material for MkDocs will set this automatically based on the - [site language][6], but it may be overridden, e.g. to support multiple + [site language][7], but it may be overridden, e.g. to support multiple languages: === "A single language" @@ -106,7 +106,7 @@ The following options are supported: `prebuild_index`{: #prebuild-index } : :octicons-milestone-24: Default: `false` · :octicons-beaker-24: - Experimental – MkDocs can generate a [prebuilt index][7] of all pages during + Experimental – MkDocs can generate a [prebuilt index][8] of all pages during build time, which provides performance improvements at the cost of more bandwidth, as it reduces the build time of the search index: @@ -126,21 +126,22 @@ them at your own risk._ [2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search [3]: https://www.mkdocs.org/user-guide/configuration/#search - [4]: https://lunrjs.com - [5]: https://github.com/MihaiValentin/lunr-languages - [6]: changing-the-language.md#site-language - [7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index + [4]: ../insiders.md + [5]: https://lunrjs.com + [6]: https://github.com/MihaiValentin/lunr-languages + [7]: changing-the-language.md#site-language + [8]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index ### Highlighting search -[:octicons-file-code-24: Source][2] · +[:octicons-file-code-24: Source][4] · :octicons-unlock-24: Feature flag · :octicons-beaker-24: Experimental · -[:octicons-heart-fill-24:{: .tx-heart } Insiders](../insiders.md){: .tx-insiders } +[:octicons-heart-fill-24:{: .tx-heart } Insiders only][4]{: .tx-insiders } -When `search.highlighting` is activated and a user clicks on a search result, -Material for MkDocs will highlight all occurrences. It can be enabled via -`mkdocs.yml` with: +When _search highlighting_ is activated and a user clicks on a search result, +Material for MkDocs will highlight all occurrences after following the link. +It can be enabled via `mkdocs.yml` with: ``` yaml theme: @@ -148,28 +149,32 @@ theme: - search.highlight ``` -When searching for `"code blocks"`, the resulting page will look like: +Searching for `"code blocks"` yields: -![Search highlighting][8] +[![Search highlighting][9]][9] - [8]: ../assets/search-highlighting.png +_Give this feature a try on [the official documentation][10] built with Material +for MkDocs Insiders!_ + + [9]: ../assets/search-highlighting.png + [10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks ### Offline search -[:octicons-file-code-24: Source][9] · -[:octicons-cpu-24: Plugin][10] · :octicons-beaker-24: Experimental +[:octicons-file-code-24: Source][11] · +[:octicons-cpu-24: Plugin][12] · :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][10] plugin in -combination with @squidfunk's [iframe-worker][11] polyfill. +security reasons. This can be mitigated with the [localsearch][12] plugin in +combination with @squidfunk's [iframe-worker][13] polyfill. -For setup instructions, refer to the [official documentation][12]. +For setup instructions, refer to the [official documentation][14]. - [9]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390 - [10]: https://github.com/wilhelmer/mkdocs-localsearch/ - [11]: https://github.com/squidfunk/iframe-worker - [12]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 + [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390 + [12]: https://github.com/wilhelmer/mkdocs-localsearch/ + [13]: https://github.com/squidfunk/iframe-worker + [14]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 ## Customization @@ -183,12 +188,12 @@ your needs. ### Query transformation -[:octicons-file-code-24: Source][13] · +[:octicons-file-code-24: Source][15] · :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][14]: +following transformations, which can be customized by [extending the theme][16]: ``` ts /** @@ -213,12 +218,12 @@ following transformations, which can be customized by [extending the theme][14]: * asterisk (wildcard) in between terms, which can be denoted by whitespace, * any non-control character, or a word boundary. * - * @param value - Query value + * @param query - Query value * * @return Transformed query value */ -function defaultTransform(value: string): string { - return value +function defaultTransform(query: string): string { + return query .split(/"([^"]+)"/g) /* => 1 */ .map((terms, i) => i & 1 ? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +") @@ -234,7 +239,7 @@ function defaultTransform(value: 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][15]: +`config` block][17]: ``` html {% block config %} @@ -251,19 +256,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. - [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts - [14]: ../customization.md#extending-the-theme - [15]: ../customization.md#overriding-blocks + [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 ### Custom search -[:octicons-file-code-24: Source][16] · +[:octicons-file-code-24: Source][18] · :octicons-mortar-board-24: Difficulty: _challenging_ -Material for MkDocs implements search as part of a [web worker][17]. If you +Material for MkDocs implements search as part of a [web worker][19]. 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][15]: +directory and [override the `config` block][17]: ``` html {% block config %} @@ -280,8 +285,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`][18] -* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][19] +* [:octicons-file-code-24: `SearchMessage`][20] +* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][21] The sequence and direction of messages is rather intuitive: @@ -290,7 +295,7 @@ The sequence and direction of messages is rather intuitive: * :octicons-arrow-right-24: `SearchQueryMessage` * :octicons-arrow-left-24: `SearchResultMessage` - [16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker - [17]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers - [18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts - [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts + [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