mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
Updated site search documentation
This commit is contained in:
squidfunk
parent
257a73780a
commit
8754188fb1
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user