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

Added documentation for search highlighting

Browse Source
This commit is contained in:
squidfunk 2020-08-02 19:10:55 +02:00
parent 2cea481b9b
commit 05465a9484
1 changed files with 47 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -131,22 +131,45 @@ them at your own risk._
[6]: changing-the-language.md#site-language [6]: changing-the-language.md#site-language
[7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index [7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
### Highlighting search
[:octicons-file-code-24: Source][2] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders](../insiders.md){: .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:
``` yaml
theme:
features:
- search.highlight
```
When searching for `"code blocks"`, the resulting page will look like:
![Search highlighting][8]
[8]: ../assets/search-highlighting.png
### Offline search ### Offline search
[:octicons-file-code-24: Source][8] · [:octicons-file-code-24: Source][9] ·
[:octicons-cpu-24: Plugin][9] · :octicons-beaker-24: Experimental [:octicons-cpu-24: Plugin][10] · :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][9] plugin in security reasons. This can be mitigated with the [localsearch][10] plugin in
combination with @squidfunk's [iframe-worker][10] polyfill. combination with @squidfunk's [iframe-worker][11] polyfill.
For setup instructions, refer to the [official documentation][11]. For setup instructions, refer to the [official documentation][12].
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390 [9]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
[9]: https://github.com/wilhelmer/mkdocs-localsearch/ [10]: https://github.com/wilhelmer/mkdocs-localsearch/
[10]: https://github.com/squidfunk/iframe-worker [11]: https://github.com/squidfunk/iframe-worker
[11]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 [12]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
## Customization ## Customization
@ -160,12 +183,12 @@ your needs.
### Query transformation ### Query transformation
[:octicons-file-code-24: Source][12] · [:octicons-file-code-24: Source][13] ·
: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][13]: following transformations, which can be customized by [extending the theme][14]:
``` ts ``` ts
/** /**
@ -211,7 +234,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][14]: `config` block][15]:
``` html ``` html
{% block config %} {% block config %}
@ -228,19 +251,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.
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[13]: ../customization.md#extending-the-theme [14]: ../customization.md#extending-the-theme
[14]: ../customization.md#overriding-blocks [15]: ../customization.md#overriding-blocks
### Custom search ### Custom search
[:octicons-file-code-24: Source][15] · [:octicons-file-code-24: Source][16] ·
:octicons-mortar-board-24: Difficulty: _challenging_ :octicons-mortar-board-24: Difficulty: _challenging_
Material for MkDocs implements search as part of a [web worker][16]. If you Material for MkDocs implements search as part of a [web worker][17]. 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][14]: directory and [override the `config` block][15]:
``` html ``` html
{% block config %} {% block config %}
@ -257,8 +280,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`][17] * [:octicons-file-code-24: `SearchMessage`][18]
* [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18] * [:octicons-file-code-24: `SearchIndex` and `SearchResult`][19]
The sequence and direction of messages is rather intuitive: The sequence and direction of messages is rather intuitive:
@ -267,7 +290,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`
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker [16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
[16]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers [17]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
[17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts [18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
[18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts