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

Improved search documentation

Browse Source
This commit is contained in:
squidfunk 2021-06-15 11:56:08 +02:00
parent c5b08e0fe8
commit e11fce36db
3 changed files with 54 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/insiders/index.md
View File

@ -16,15 +16,15 @@ to [get access to Insiders][2].
</div> </div>
<figcaption markdown="1"> <figcaption markdown="1">
A demo is worth a thousand words — check it out at The official documentation is built with Insiders
[squidfunk.github.io/mkdocs-material-insiders][3] [squidfunk.github.io/mkdocs-material][3]
</figcaption> </figcaption>
</figure> </figure>
[1]: #how-sponsorship-works [1]: #how-sponsorship-works
[2]: #how-to-become-a-sponsor [2]: #how-to-become-a-sponsor
[3]: https://squidfunk.github.io/mkdocs-material-insiders/ [3]: https://squidfunk.github.io/mkdocs-material/
## How sponsorship works ## How sponsorship works

10
docs/setup/setting-up-navigation.md
View File

@ -245,18 +245,8 @@ theme:
- navigation.top - navigation.top
``` ```
<figure markdown="1">
[![back-to-top button][20]][20] [![back-to-top button][20]][20]
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-insiders][21]
</figcaption>
</figure>
[19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_top.scss [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_top.scss
[20]: ../assets/screenshots/back-to-top.png [20]: ../assets/screenshots/back-to-top.png
[21]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button [21]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button

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

@ -151,23 +151,13 @@ theme:
- search.suggest - 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:
<figure markdown="1"> [![Search suggestions][10]][10]
[![Search suggestions][9]][9]
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-insiders][10]
</figcaption>
</figure>
[8]: ../insiders/index.md [8]: ../insiders/index.md
[9]: ../assets/screenshots/search-suggestions.png [9]: ?q=search+su
[10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?q=code+high [10]: ../assets/screenshots/search-suggestions.png
### Search highlighting ### Search highlighting
@ -186,22 +176,15 @@ theme:
- search.highlight - search.highlight
``` ```
Searching for ^^code highlighting^^ yields: Searching for [:octicons-search-24: ^^code highlighting^^][11] yields:
<figure markdown="1"> [![Search highlighting][12]][12]
[![Search highlighting][11]][11]
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-insiders][12]
</figcaption> </figcaption>
</figure> </figure>
[11]: ../assets/screenshots/search-highlighting.png [11]: ../reference/code-blocks.md?h=code+blocks
[12]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks [12]: ../assets/screenshots/search-highlighting.png
### Search sharing ### Search sharing
@ -223,37 +206,26 @@ theme:
When a user clicks the share button, the URL is automatically copied to the When a user clicks the share button, the URL is automatically copied to the
clipboard. clipboard.
<figure markdown="1">
[![Search sharing][13]][13] [![Search sharing][13]][13]
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-insiders][14]
</figcaption>
</figure>
[13]: ../assets/screenshots/search-share.png [13]: ../assets/screenshots/search-share.png
[14]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-site-search/?q=share+search
### Offline search ### Offline search
[:octicons-file-code-24: Source][15] · [:octicons-file-code-24: Source][14] ·
[:octicons-cpu-24: Plugin][16] · :octicons-beaker-24: Experimental [:octicons-cpu-24: Plugin][15] · :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][16] plugin in security reasons. This can be mitigated with the [localsearch][15] plugin in
combination with @squidfunk's [iframe-worker][17] polyfill. 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 [14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[16]: https://github.com/wilhelmer/mkdocs-localsearch/ [15]: https://github.com/wilhelmer/mkdocs-localsearch/
[17]: https://github.com/squidfunk/iframe-worker [16]: https://github.com/squidfunk/iframe-worker
[18]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 [17]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
!!! tip !!! 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 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 page-specific boosts, which can be defined for each page by leveraging the
[Metadata][19] extension: [Metadata][18] extension:
``` bash ``` bash
--- ---
@ -283,7 +255,7 @@ search:
... ...
``` ```
[19]: ../../reference/meta-tags/#metadata [18]: ../../reference/meta-tags/#metadata
## Customization ## Customization
@ -297,52 +269,45 @@ your needs.
### Query transformation ### Query transformation
[:octicons-file-code-24: Source][20] · [:octicons-file-code-24: Source][19] ·
: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][21]: following transformations, which can be customized by [extending the theme][20]:
``` ts ``` 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 { export function defaultTransform(query: string): string {
return query return query
.split(/"([^"]+)"/g) /* => 1 */ .split(/"([^"]+)"/g) /* (1) */
.map((terms, index) => index & 1 .map((terms, index) => index & 1
? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +") ? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +")
: terms : terms
) )
.join("") .join("")
.replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* => 2 */ .replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* (2) */
.trim() /* => 3 */ .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` 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 themes, 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][22]: `config` block][21]:
``` html ``` html
{% block config %} {% 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 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.
[20]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[21]: ../customization.md#extending-the-theme [20]: ../customization.md#extending-the-theme
[22]: ../customization.md#overriding-blocks-recommended [21]: ../customization.md#overriding-blocks-recommended
### Custom search ### Custom search
[:octicons-file-code-24: Source][23] · [:octicons-file-code-24: Source][22] ·
:octicons-mortar-board-24: Difficulty: _challenging_ :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 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 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 ``` html
{% block config %} {% 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 message. See the following interface definitions to learn about the message
formats: formats:
- [:octicons-file-code-24: `SearchMessage`][25] - [:octicons-file-code-24: `SearchMessage`][24]
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][26] - [:octicons-file-code-24: `SearchIndex` and `SearchResult`][25]
The sequence and direction of messages is rather intuitive: 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-right-24: `SearchQueryMessage`
- :octicons-arrow-left-24: `SearchResultMessage` - :octicons-arrow-left-24: `SearchResultMessage`
[23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker [22]: 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 [23]: 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 [24]: 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 [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts