OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated site search documentation

Browse Source
This commit is contained in:
squidfunk 2020-08-02 22:09:44 +02:00
parent 257a73780a
commit 8754188fb1
2 changed files with 54 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/insiders.md
View File

@ -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. availability. Bugfixes will always be released simultaneously in both editions.
See the [roadmap][4] for a list of already available and upcoming features, and 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 for demonstration purposes, [the official documentation][5] built with Material
MkDocs Insiders. for MkDocs Insiders.
[4]: #roadmap [4]: #roadmap
[5]: https://squidfunk.github.io/mkdocs-material-insiders/ [5]: https://squidfunk.github.io/mkdocs-material-insiders/
@ -75,7 +75,7 @@ in Material for MkDocs Insiders.
### Madame Jeanette ### Madame Jeanette
[:octicons-fire-24: Funding goal: __$500__][6] · [: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: New features and improvements for _search_, including:
@ -88,11 +88,11 @@ New features and improvements for _search_, including:
### Prairie Fire ### Prairie Fire
[:octicons-fire-24: Funding goal: __$1,000__][6] · [: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: 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 - [ ] Better support for wide screens, i.e. more horizontal space
- [ ] Table of contents can be moved into navigation for more space - [ ] Table of contents can be moved into navigation for more space
- [ ] Table of contents shows which sections have search results - [ ] Table of contents shows which sections have search results

93
docs/setup/setting-up-site-search.md
View File

@ -17,10 +17,10 @@ made available [offline][1].
[:octicons-file-code-24: Source][2] · [:octicons-file-code-24: Source][2] ·
[:octicons-cpu-24: Plugin][3] · [: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, 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 It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins
are used: are used:
@ -34,9 +34,9 @@ The following options are supported:
`lang`{: #lang } `lang`{: #lang }
: :octicons-milestone-24: Default: _automatically set_ – This option allows : :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 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: languages:
=== "A single language" === "A single language"
@ -106,7 +106,7 @@ The following options are supported:
`prebuild_index`{: #prebuild-index } `prebuild_index`{: #prebuild-index }
: :octicons-milestone-24: Default: `false` · :octicons-beaker-24: : :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 build time, which provides performance improvements at the cost of more
bandwidth, as it reduces the build time of the search index: 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 [2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
[3]: https://www.mkdocs.org/user-guide/configuration/#search [3]: https://www.mkdocs.org/user-guide/configuration/#search
[4]: https://lunrjs.com [4]: ../insiders.md
[5]: https://github.com/MihaiValentin/lunr-languages [5]: https://lunrjs.com
[6]: changing-the-language.md#site-language [6]: https://github.com/MihaiValentin/lunr-languages
[7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index [7]: changing-the-language.md#site-language
[8]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
### Highlighting search ### Highlighting search
[:octicons-file-code-24: Source][2] · [:octicons-file-code-24: Source][4] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :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, 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 Material for MkDocs will highlight all occurrences after following the link.
`mkdocs.yml` with: It can be enabled via `mkdocs.yml` with:
``` yaml ``` yaml
theme: theme:
@ -148,28 +149,32 @@ theme:
- search.highlight - 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 ### Offline search
[:octicons-file-code-24: Source][9] · [:octicons-file-code-24: Source][11] ·
[:octicons-cpu-24: Plugin][10] · :octicons-beaker-24: Experimental [:octicons-cpu-24: Plugin][12] · :octicons-beaker-24: Experimental
If you distribute your documentation as `*.html` files, the built-in search 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 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 security reasons. This can be mitigated with the [localsearch][12] plugin in
combination with @squidfunk's [iframe-worker][11] polyfill. 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 [11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
[10]: https://github.com/wilhelmer/mkdocs-localsearch/ [12]: https://github.com/wilhelmer/mkdocs-localsearch/
[11]: https://github.com/squidfunk/iframe-worker [13]: https://github.com/squidfunk/iframe-worker
[12]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 [14]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
## Customization ## Customization
@ -183,12 +188,12 @@ your needs.
### Query transformation ### Query transformation
[:octicons-file-code-24: Source][13] · [:octicons-file-code-24: Source][15] ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
When a user enters a query into the search box, the query is pre-processed 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 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 ``` 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, * asterisk (wildcard) in between terms, which can be denoted by whitespace,
* any non-control character, or a word boundary. * any non-control character, or a word boundary.
* *
* @param value - Query value * @param query - Query value
* *
* @return Transformed query value * @return Transformed query value
*/ */
function defaultTransform(value: string): string { function defaultTransform(query: string): string {
return value return query
.split(/"([^"]+)"/g) /* => 1 */ .split(/"([^"]+)"/g) /* => 1 */
.map((terms, i) => i & 1 .map((terms, i) => i & 1
? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +") ? 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` 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 template, both of which don't transform the query prior to submission, or
customize the `transform` function, you can do this by [overriding the customize the `transform` function, you can do this by [overriding the
`config` block][15]: `config` block][17]:
``` html ``` html
{% block config %} {% 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 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. 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 [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[14]: ../customization.md#extending-the-theme [16]: ../customization.md#extending-the-theme
[15]: ../customization.md#overriding-blocks [17]: ../customization.md#overriding-blocks
### Custom search ### Custom search
[:octicons-file-code-24: Source][16] · [:octicons-file-code-24: Source][18] ·
:octicons-mortar-board-24: Difficulty: _challenging_ :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 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` 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 ``` html
{% block config %} {% 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 of the message. See the following interface definitions to learn about the
message formats: message formats:
* [:octicons-file-code-24: `SearchMessage`][18] * [:octicons-file-code-24: `SearchMessage`][20]
* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][19] * [:octicons-file-code-24: `SearchIndex` and `SearchResult`][21]
The sequence and direction of messages is rather intuitive: 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-right-24: `SearchQueryMessage`
* :octicons-arrow-left-24: `SearchResultMessage` * :octicons-arrow-left-24: `SearchResultMessage`
[16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker [18]: 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 [19]: 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 [20]: 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 [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts