From e11fce36db2f57d676198c41dad60c58d0bc6d90 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Tue, 15 Jun 2021 11:56:08 +0200 Subject: [PATCH] Improved search documentation --- docs/insiders/index.md | 6 +- docs/setup/setting-up-navigation.md | 10 -- docs/setup/setting-up-site-search.md | 137 ++++++++++----------------- 3 files changed, 54 insertions(+), 99 deletions(-) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index de7f868e6..448354b13 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -16,15 +16,15 @@ to [get access to Insiders][2].
-A demo is worth a thousand words — check it out at -[squidfunk.github.io/mkdocs-material-insiders][3] +The official documentation is built with Insiders +[squidfunk.github.io/mkdocs-material][3]
[1]: #how-sponsorship-works [2]: #how-to-become-a-sponsor - [3]: https://squidfunk.github.io/mkdocs-material-insiders/ + [3]: https://squidfunk.github.io/mkdocs-material/ ## How sponsorship works diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 64f438bc3..b082c1f4d 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -245,18 +245,8 @@ theme: - navigation.top ``` -
- [![back-to-top button][20]][20] -
- -A demo is worth a thousand words — check it out at -[squidfunk.github.io/mkdocs-material-insiders][21] - -
-
- [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_top.scss [20]: ../assets/screenshots/back-to-top.png [21]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index f9e2141ae..f853bb611 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -151,23 +151,13 @@ theme: - search.suggest ``` -Searching for ^^search su^^ yields ^^search suggestions^^ as a suggestion: +Searching for [:octicons-search-24: ^^search su^^][9] yields ^^search suggestions^^ as a suggestion: -
- -[![Search suggestions][9]][9] - -
- -A demo is worth a thousand words — check it out at -[squidfunk.github.io/mkdocs-material-insiders][10] - -
-
+[![Search suggestions][10]][10] [8]: ../insiders/index.md - [9]: ../assets/screenshots/search-suggestions.png - [10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?q=code+high + [9]: ?q=search+su + [10]: ../assets/screenshots/search-suggestions.png ### Search highlighting @@ -186,22 +176,15 @@ theme: - search.highlight ``` -Searching for ^^code highlighting^^ yields: +Searching for [:octicons-search-24: ^^code highlighting^^][11] yields: -
- -[![Search highlighting][11]][11] - -
- -A demo is worth a thousand words — check it out at -[squidfunk.github.io/mkdocs-material-insiders][12] +[![Search highlighting][12]][12]
- [11]: ../assets/screenshots/search-highlighting.png - [12]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks + [11]: ../reference/code-blocks.md?h=code+blocks + [12]: ../assets/screenshots/search-highlighting.png ### Search sharing @@ -223,37 +206,26 @@ theme: When a user clicks the share button, the URL is automatically copied to the clipboard. -
- [![Search sharing][13]][13] -
- -A demo is worth a thousand words — check it out at -[squidfunk.github.io/mkdocs-material-insiders][14] - -
-
- [13]: ../assets/screenshots/search-share.png - [14]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-site-search/?q=share+search ### Offline search -[:octicons-file-code-24: Source][15] · -[:octicons-cpu-24: Plugin][16] · :octicons-beaker-24: Experimental +[:octicons-file-code-24: Source][14] · +[:octicons-cpu-24: Plugin][15] · :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][16] plugin in -combination with @squidfunk's [iframe-worker][17] polyfill. +security reasons. This can be mitigated with the [localsearch][15] plugin in +combination with @squidfunk's [iframe-worker][16] polyfill. -For setup instructions, refer to the [official documentation][18]. +For setup instructions, refer to the [official documentation][17]. - [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html - [16]: https://github.com/wilhelmer/mkdocs-localsearch/ - [17]: https://github.com/squidfunk/iframe-worker - [18]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 + [14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html + [15]: https://github.com/wilhelmer/mkdocs-localsearch/ + [16]: https://github.com/squidfunk/iframe-worker + [17]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 !!! tip @@ -271,7 +243,7 @@ For setup instructions, refer to the [official documentation][18]. In order to give specific pages a higher relevance in search, [lunr][4] supports page-specific boosts, which can be defined for each page by leveraging the -[Metadata][19] extension: +[Metadata][18] extension: ``` bash --- @@ -283,7 +255,7 @@ search: ... ``` - [19]: ../../reference/meta-tags/#metadata + [18]: ../../reference/meta-tags/#metadata ## Customization @@ -297,52 +269,45 @@ your needs. ### Query transformation -[:octicons-file-code-24: Source][20] · +[:octicons-file-code-24: Source][19] · :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][21]: +following transformations, which can be customized by [extending the theme][20]: ``` ts -/** - * Default transformation function - * - * 1. Search for terms in quotation marks and prepend a `+` modifier to denote - * that the resulting document must contain all terms, converting the query - * to an `AND` query (as opposed to the default `OR` behavior). While users - * may expect terms enclosed in quotation marks to map to span queries, i.e. - * for which order is important, `lunr` doesn't support them, so the best - * we can do is to convert the terms to an `AND` query. - * - * 2. Replace control characters which are not located at the beginning of the - * query or preceded by white space, or are not followed by a non-whitespace - * character or are at the end of the query string. Furthermore, filter - * unmatched quotation marks. - * - * 3. Trim excess whitespace from left and right. - * - * @param query - Query value - * - * @returns Transformed query value - */ export function defaultTransform(query: string): string { return query - .split(/"([^"]+)"/g) /* => 1 */ + .split(/"([^"]+)"/g) /* (1) */ .map((terms, index) => index & 1 ? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +") : terms ) .join("") - .replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* => 2 */ - .trim() /* => 3 */ + .replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* (2) */ + .trim() /* (3) */ } ``` +1. Search for terms in quotation marks and prepend a `+` modifier to denote + that the resulting document must contain all terms, converting the query + to an `AND` query (as opposed to the default `OR` behavior). While users + may expect terms enclosed in quotation marks to map to span queries, i.e. + for which order is important, `lunr` doesn't support them, so the best + we can do is to convert the terms to an `AND` query. + +2. Replace control characters which are not located at the beginning of the + query or preceded by white space, or are not followed by a non-whitespace + character or are at the end of the query string. Furthermore, filter + unmatched quotation marks. + +3. Trim excess whitespace from left and right. + If you want to switch to the default behavior of the `mkdocs` and `readthedocs` themes, 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][22]: +`config` block][21]: ``` html {% block config %} @@ -360,19 +325,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. - [20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts - [21]: ../customization.md#extending-the-theme - [22]: ../customization.md#overriding-blocks-recommended + [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts + [20]: ../customization.md#extending-the-theme + [21]: ../customization.md#overriding-blocks-recommended ### Custom search -[:octicons-file-code-24: Source][23] · +[:octicons-file-code-24: Source][22] · :octicons-mortar-board-24: Difficulty: _challenging_ -Material for MkDocs implements search as part of a [web worker][24]. If you +Material for MkDocs implements search as part of a [web worker][23]. 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][21]: +`docs` directory and [override the `config` block][20]: ``` html {% block config %} @@ -390,8 +355,8 @@ 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`][25] -- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][26] +- [:octicons-file-code-24: `SearchMessage`][24] +- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][25] The sequence and direction of messages is rather intuitive: @@ -400,7 +365,7 @@ The sequence and direction of messages is rather intuitive: - :octicons-arrow-right-24: `SearchQueryMessage` - :octicons-arrow-left-24: `SearchResultMessage` - [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker - [24]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers - [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts - [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts + [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker + [23]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers + [24]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts + [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts