mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Updated documentation
This commit is contained in:
squidfunk
parent
babc28f9fe
commit
c4cf616670
@ -63,7 +63,7 @@ _Example_:
|
||||
|
||||
_Result_:
|
||||
|
||||
[Jump to footnote at the bottom of the page](#fn:1)
|
||||
[:octicons-arrow-down-24: Jump to footnote](#fn:1)
|
||||
|
||||
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
@ -87,4 +87,4 @@ _Result_:
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
|
||||
auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
[Jump to footnote at the bottom of the page](#fn:2)
|
||||
[:octicons-arrow-down-24: Jump to footnote](#fn:2)
|
||||
|
||||
@ -198,7 +198,8 @@ The following configuration options are supported:
|
||||
|
||||
`enable_creation_date`{ #enable-creation-date }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` – Enables the display of the
|
||||
: [:octicons-tag-24: 7.1.4][enable_creation_date support] ·
|
||||
:octicons-milestone-24: Default: `false` – Enables the display of the
|
||||
creation date of the file associated with the page next to the last updated
|
||||
date at the bottom of the page:
|
||||
|
||||
@ -215,3 +216,4 @@ them at your own risk.
|
||||
|
||||
[git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
|
||||
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
|
||||
[enable_creation_date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.4
|
||||
|
||||
@ -76,7 +76,7 @@ The following languages are supported:
|
||||
- `zh` – Chinese (Simplified)
|
||||
- `zh-Hant` – Chinese (Traditional)
|
||||
- `zh-TW` – Chinese (Taiwanese)
|
||||
- [Add language](https://bit.ly/38F5RCa)
|
||||
- [Add language]
|
||||
|
||||
</div>
|
||||
|
||||
@ -85,6 +85,7 @@ the default slug function works. Consider using a [Unicode-aware slug function].
|
||||
|
||||
[language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
|
||||
[Unicode-aware slug function]: setting-up-navigation.md#slugify
|
||||
[Add language]: https://bit.ly/38F5RCa
|
||||
|
||||
### Site language selector
|
||||
|
||||
|
||||
@ -231,7 +231,7 @@ This feature flag is not compatible with [`toc.integrate`][toc.integrate].
|
||||
[:octicons-tag-24: 6.2.0][toc.integrate support] ·
|
||||
:octicons-unlock-24: Feature flag
|
||||
|
||||
When navigation integration for the table of contents is enabled, it is always
|
||||
When navigation integration for the [table of contents] is enabled, it is always
|
||||
rendered as part of the navigation sidebar on the left. Add the following lines
|
||||
to `mkdocs.yml`:
|
||||
|
||||
@ -252,6 +252,7 @@ theme:
|
||||
This feature flag is not compatible with [`navigation.indexes`]
|
||||
[navigation.indexes].
|
||||
|
||||
[table of contents]: extensions/python-markdown.md#table-of-contents
|
||||
[toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
|
||||
[toc.integrate enabled]: ../assets/screenshots/toc-integrate.png
|
||||
[toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png
|
||||
|
||||
@ -9,25 +9,20 @@ search:
|
||||
Material for MkDocs provides an excellent, client-side search implementation,
|
||||
omitting the need for the integration of third-party services, which might
|
||||
be tricky to integrate to be compliant with data privacy regulations. Moreover,
|
||||
with some effort, search can be made available [offline][1].
|
||||
with some effort, search can be made available [offline].
|
||||
|
||||
[1]: #offline-search
|
||||
[offline]: #offline-search
|
||||
|
||||
## Configuration
|
||||
|
||||
### Built-in search
|
||||
|
||||
!!! danger "[Search: better, faster, smaller](../blog/2021/search-better-faster-smaller.md)"
|
||||
[:octicons-tag-24: 0.1.0][search support] ·
|
||||
:octicons-cpu-24: Plugin
|
||||
|
||||
We rebuilt the search plugin and integration from the ground up, introducing [rich search previews](../blog/2021/search-better-faster-smaller.md#rich-search-previews), much better [tokenizer support](../blog/2021/search-better-faster-smaller.md#tokenizer-lookahead), [more accurate highlighting](../blog/2021/search-better-faster-smaller.md#accurate-highlighting) and much more. Read the [blog article](../blog/2021/search-better-faster-smaller.md) to learn more about our new search implementation. Start using it immediately by [becoming a sponsor][20]!
|
||||
|
||||
[:octicons-file-code-24: Source][2] ·
|
||||
[:octicons-cpu-24: Plugin][3] ·
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Better in Insiders][20]{ .mdx-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].
|
||||
It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins
|
||||
The built-in search plugin integrates seamlessly with Material for MkDocs,
|
||||
adding multilingual client-side search with [lunr] and [lunr-languages]. It's
|
||||
enabled by default, but must be re-added to `mkdocs.yml` when other plugins
|
||||
are used:
|
||||
|
||||
``` yaml
|
||||
@ -35,14 +30,14 @@ plugins:
|
||||
- search
|
||||
```
|
||||
|
||||
The following options are supported:
|
||||
The following configuration options are supported:
|
||||
|
||||
`lang`{ #search-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].
|
||||
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], but it may be overridden, e.g. to support multiple
|
||||
languages:
|
||||
|
||||
=== "A single language"
|
||||
@ -58,11 +53,15 @@ The following options are supported:
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
lang:
|
||||
lang: # (1)
|
||||
- en
|
||||
- ru
|
||||
```
|
||||
|
||||
1. Be aware that including support for other languages increases the
|
||||
general JavaScript payload by around 20kb (before `gzip`) and by
|
||||
another 15-30kb per language.
|
||||
|
||||
The following languages are supported:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
@ -89,14 +88,9 @@ The following options are supported:
|
||||
|
||||
</div>
|
||||
|
||||
_Material for MkDocs also tries to support languages that are not part of
|
||||
this list by choosing the stemmer yielding the best result automatically_.
|
||||
|
||||
!!! warning "Only specify the languages you really need"
|
||||
|
||||
Be aware that including support for other languages increases the general
|
||||
JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
|
||||
per language.
|
||||
Material for MkDocs goes to great lengths to support languages that are not
|
||||
part of this list by automatically falling back to the stemmer yielding the
|
||||
best result.
|
||||
|
||||
`separator`{ #search-separator }
|
||||
|
||||
@ -108,13 +102,21 @@ The following options are supported:
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
separator: '[\s\-\.]+'
|
||||
separator: '[\s\-\.]' # (1)
|
||||
```
|
||||
|
||||
~~`prebuild_index`~~{ #search-prebuild-index }[^1]
|
||||
1. Tokenization itself is carried out by [lunr's default tokenizer], which
|
||||
doesn't allow for lookahead or separators spanning multiple characters.
|
||||
|
||||
For more finegrained control over the tokenization process, see the
|
||||
section on [tokenizer lookahead].
|
||||
|
||||
<div class="mdx-deprecated" markdown>
|
||||
|
||||
`prebuild_index`{ #search-prebuild-index }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` · :octicons-archive-24: Deprecated
|
||||
– MkDocs can generate a [prebuilt index][7] of all pages during
|
||||
· :octicons-trash-24: 8.0.0 – MkDocs can generate a [prebuilt index] 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:
|
||||
|
||||
@ -124,36 +126,126 @@ The following options are supported:
|
||||
prebuild_index: true
|
||||
```
|
||||
|
||||
This may be beneficial for large documentation projects served with
|
||||
appropriate headers, i.e. `Content-Encoding: gzip`, but benchmarking before
|
||||
deployment is recommended.
|
||||
Note that this configuration option was deprecated, as the [new search
|
||||
plugin] generates up to [50% smaller] search indexes, doubling search
|
||||
performance.
|
||||
|
||||
[^1]:
|
||||
The `prebuild_index` feature was deprecated in 7.3.0 and will be removed
|
||||
in 8.x. Insiders removed support in 3.0.0 with the advent of the new
|
||||
search plugin.
|
||||
[:octicons-arrow-right-24: Read more on the new search plugin]
|
||||
[new search plugin]
|
||||
|
||||
_Material for MkDocs doesn't provide official support for the other options of
|
||||
this plugin, so they may be supported but might yield unexpected results.
|
||||
Use them at your own risk._
|
||||
</div>
|
||||
|
||||
[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
|
||||
The other configuration options of this plugin are not officially supported
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
[search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[lunr]: https://lunrjs.com
|
||||
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
|
||||
[lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
|
||||
[site language]: changing-the-language.md#site-language
|
||||
[tokenizer lookahead]: #tokenizer-lookahead
|
||||
[prebuilt index]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
|
||||
[50% smaller]: ../blog/2021/search-better-faster-smaller.md#benchmarks
|
||||
|
||||
### Rich search previews
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-3.0.0][Insiders] ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
Insiders ships rich search previews as part of the [new search plugin], which
|
||||
will render code blocks directly in the search result, and highlight all
|
||||
occurrences inside those blocks:
|
||||
|
||||
=== "Insiders"
|
||||
|
||||
![search preview now]
|
||||
|
||||
=== "Material for MkDocs"
|
||||
|
||||
![search preview before]
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[new search plugin]: ../blog/2021/search-better-faster-smaller.md
|
||||
[search preview now]: ../blog/2021/search-better-faster-smaller/search-preview-now.png
|
||||
[search preview before]: ../blog/2021/search-better-faster-smaller/search-preview-before.png
|
||||
|
||||
### Tokenizer lookahead
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-3.0.0][Insiders] ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
Insiders allows for more complex configurations of the [`separator`][separator]
|
||||
setting as part of the [new search plugin], yielding more influence on the way
|
||||
documents are tokenized:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
|
||||
```
|
||||
|
||||
The following section explains what can be achieved with tokenizer lookahead:
|
||||
|
||||
=== "Case changes"
|
||||
|
||||
```
|
||||
(?!\b)(?=[A-Z][a-z])
|
||||
```
|
||||
|
||||
`PascalCase` and `camelCase` are used as naming conventions in many
|
||||
programming languages. By adding this match group to the [`separator`]
|
||||
[separator], [words are split at case changes], tokenizing the word
|
||||
`PascalCase` into `Pascal` and `Case`, so both terms can be searched
|
||||
individually.
|
||||
|
||||
[:octicons-arrow-right-24: Read more on tokenizing case changes]
|
||||
[tokenize case changes]
|
||||
|
||||
=== "Version numbers"
|
||||
|
||||
```
|
||||
\.(?!\d)
|
||||
```
|
||||
|
||||
When `.` is added to the [`separator`][separator], version numbers would be
|
||||
split into parts, rendering them undiscoverable via search. By adding
|
||||
this match group, a small lookahead is introduced, so version numbers will
|
||||
remain as they are, and can be found through search.
|
||||
|
||||
[:octicons-arrow-right-24: Read more on tokenizing version numbers]
|
||||
[tokenize version numbers]
|
||||
|
||||
=== "HTML/XML tags"
|
||||
|
||||
```
|
||||
&[lg]t;
|
||||
```
|
||||
|
||||
If your documentation includes HTML/XML code examples, you may want to allow
|
||||
users to find specific tag names. Unfortunately, the `<` and `>` control
|
||||
characters are encoded in code blocks as `<` and `>`. Adding this
|
||||
expression to the separator allows for just that.
|
||||
|
||||
[:octicons-arrow-right-24: Read more on tokenizing HTML/XML tags]
|
||||
[tokenize html-xml tags]
|
||||
|
||||
[separator]: #search-separator
|
||||
[words are split at case changes]: ?q=searchHighlight
|
||||
[tokenize case changes]: ../blog/2021/search-better-faster-smaller.md#case-changes
|
||||
[tokenize version numbers]: ../blog/2021/search-better-faster-smaller.md#version-numbers
|
||||
[tokenize html-xml tags]: ../blog/2021/search-better-faster-smaller.md#htmlxml-tags
|
||||
|
||||
### Search suggestions
|
||||
|
||||
[:octicons-tag-24: 7.2.0][search.suggest support] ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: 7.2.0][Search suggestions support]
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
When search suggestions are enabled, the search will display the likeliest
|
||||
completion for the last word, saving the user many key strokes by accepting the
|
||||
suggestion with the ++arrow-right++ key.
|
||||
|
||||
completion for the last word which can be accepted with the ++arrow-right++ key.
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
@ -162,20 +254,17 @@ theme:
|
||||
- search.suggest
|
||||
```
|
||||
|
||||
Searching for [:octicons-search-24: search su][9] yields ^^search suggestions^^ as a suggestion:
|
||||
Searching for [:octicons-search-24: search su][search.suggest example] yields
|
||||
^^search suggestions^^ as a suggestion.
|
||||
|
||||
[![Search suggestions][10]][10]
|
||||
|
||||
[Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
|
||||
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/suggest/index.ts
|
||||
[9]: ?q=search+su
|
||||
[10]: ../assets/screenshots/search-suggestions.png
|
||||
[search.suggest support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
|
||||
[search.suggest example]: ?q=search+su
|
||||
|
||||
### Search highlighting
|
||||
|
||||
[:octicons-tag-24: 7.2.0][search.highlight support] ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: 7.2.0][Search highlighting support]
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
When search highlighting is enabled and a user clicks on a search result,
|
||||
Material for MkDocs will highlight all occurrences after following the link.
|
||||
@ -187,20 +276,17 @@ theme:
|
||||
- search.highlight
|
||||
```
|
||||
|
||||
Searching for [:octicons-search-24: code blocks][12] yields:
|
||||
Searching for [:octicons-search-24: code blocks][search.highlight example]
|
||||
highlights all occurrences of both terms.
|
||||
|
||||
[![Search highlighting][13]][13]
|
||||
|
||||
[Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
|
||||
[11]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/highlight/index.ts
|
||||
[12]: ../reference/code-blocks.md?h=code+blocks
|
||||
[13]: ../assets/screenshots/search-highlighting.png
|
||||
[search.highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
|
||||
[search.highlight example]: ../reference/code-blocks.md?h=code+blocks
|
||||
|
||||
### Search sharing
|
||||
|
||||
[:octicons-tag-24: 7.2.0][search.share support] ·
|
||||
:octicons-unlock-24: Feature flag ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: 7.2.0][Search highlighting support]
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
When search sharing is activated, a :material-share-variant: share button is
|
||||
rendered next to the reset button, which allows to deep link to the current
|
||||
@ -215,28 +301,24 @@ theme:
|
||||
When a user clicks the share button, the URL is automatically copied to the
|
||||
clipboard.
|
||||
|
||||
[![Search sharing][15]][15]
|
||||
|
||||
[Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
|
||||
[14]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/components/search/share/index.ts
|
||||
[15]: ../assets/screenshots/search-share.png
|
||||
[search.share support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
|
||||
|
||||
### Offline search
|
||||
|
||||
[:octicons-file-code-24: Source][16] ·
|
||||
[:octicons-cpu-24: Plugin][17]
|
||||
[:octicons-tag-24: 5.0.0][offline search support] ·
|
||||
[:octicons-cpu-24: Plugin][localsearch]
|
||||
|
||||
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][17] plugin in
|
||||
combination with @squidfunk's [iframe-worker][18] polyfill.
|
||||
security reasons. This can be mitigated with the [localsearch] plugin in
|
||||
combination with @squidfunk's [iframe-worker] polyfill.
|
||||
|
||||
For setup instructions, refer to the [official documentation][19].
|
||||
For setup instructions, refer to the [localsearch documentation].
|
||||
|
||||
[16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
|
||||
[17]: https://github.com/wilhelmer/mkdocs-localsearch/
|
||||
[18]: https://github.com/squidfunk/iframe-worker
|
||||
[19]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
|
||||
[offline search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
|
||||
[localsearch]: https://github.com/wilhelmer/mkdocs-localsearch/
|
||||
[iframe-worker]: https://github.com/squidfunk/iframe-worker
|
||||
[localsearch documentation]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
|
||||
|
||||
!!! tip
|
||||
|
||||
@ -249,39 +331,36 @@ For setup instructions, refer to the [official documentation][19].
|
||||
### Search boosting
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
:octicons-note-24: Metadata ·
|
||||
[:octicons-tag-24: insiders-2.8.0][Insiders]
|
||||
|
||||
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][21] extension:
|
||||
When [Metadata] is enabled, pages can be boosted in search with custom front
|
||||
matter, which will make them rank higher. Add the following lines at the top of
|
||||
a Markdown file:
|
||||
|
||||
``` bash
|
||||
---
|
||||
search:
|
||||
boost: 100
|
||||
boost: 2 # (1)
|
||||
---
|
||||
|
||||
# Document title
|
||||
...
|
||||
```
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[20]: ../insiders/index.md
|
||||
[21]: ../reference/meta-tags.md#metadata
|
||||
1. :woman_in_lotus_position: When boosting pages, be gentle and start with
|
||||
__low values__.
|
||||
|
||||
[Metadata]: extensions/python-markdown.md#metadata
|
||||
|
||||
### Search exclusion
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
||||
:octicons-note-24: Metadata ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
[:octicons-tag-24: insiders-3.1.0][Insiders]
|
||||
[:octicons-tag-24: insiders-3.1.0][Insiders] ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
#### Excluding pages
|
||||
|
||||
Sometimes, it's necessary to exclude a page from the search index, which can be
|
||||
achieved by adding the following front matter using the [Metadata][21]
|
||||
extension:
|
||||
When [Metadata] is enabled, pages can be excluded from search with custom front
|
||||
matter, removing them from the index. Add the following lines at the top of a
|
||||
Markdown file:
|
||||
|
||||
``` bash
|
||||
---
|
||||
@ -295,11 +374,11 @@ search:
|
||||
|
||||
#### Excluding sections
|
||||
|
||||
With the help of the [Attribute List][22] extension, it's possible to exclude a
|
||||
specific section of a page from search by adding the `{ data-search-exclude }`
|
||||
pragma after the Markdown heading:
|
||||
When [Attribute Lists] is enabled, specific sections of pages can be excluded
|
||||
from search by adding the `{ data-search-exclude }` pragma after a Markdown
|
||||
heading:
|
||||
|
||||
=== "`docs/page.md`"
|
||||
=== ":octicons-file-code-16: docs/page.md"
|
||||
|
||||
``` markdown
|
||||
# Document title
|
||||
@ -313,7 +392,7 @@ pragma after the Markdown heading:
|
||||
The content of this section is excluded
|
||||
```
|
||||
|
||||
=== "`search_index.json`"
|
||||
=== ":octicons-codescan-16: search_index.json"
|
||||
|
||||
``` json
|
||||
{
|
||||
@ -333,15 +412,15 @@ pragma after the Markdown heading:
|
||||
}
|
||||
```
|
||||
|
||||
[22]: ../reference/images.md#attribute-list
|
||||
[Attribute Lists]: extensions/python-markdown.md#attribute-lists
|
||||
|
||||
#### Excluding blocks
|
||||
|
||||
If even more fine-grained control is needed, content blocks can be excluded
|
||||
from search sections with a `{ data-search-exclude }` pragma, so they will not
|
||||
be included in the search index:
|
||||
When [Attribute Lists] is enabled, specific sections of pages can be excluded
|
||||
from search by adding the `{ data-search-exclude }` pragma after a Markdown
|
||||
inline- or block-level element:
|
||||
|
||||
=== "`docs/page.md`"
|
||||
=== ":octicons-file-code-16: docs/page.md"
|
||||
|
||||
``` markdown
|
||||
# Document title
|
||||
@ -352,7 +431,7 @@ be included in the search index:
|
||||
{ data-search-exclude }
|
||||
```
|
||||
|
||||
=== "`search_index.json`"
|
||||
=== ":octicons-codescan-16: search_index.json"
|
||||
|
||||
``` json
|
||||
{
|
||||
@ -370,8 +449,8 @@ be included in the search index:
|
||||
## Customization
|
||||
|
||||
The search implementation of Material for MkDocs is probably its most
|
||||
sophisticated feature, as it tries to balance a _great typeahead experience_,
|
||||
_good performance_, _accessibility_, and a result list that is _easy to scan_.
|
||||
sophisticated feature, as it tries to balance a great typeahead experience,
|
||||
good performance, accessibility, and a result list that is easy to scan.
|
||||
This is where Material for MkDocs deviates from other themes.
|
||||
|
||||
The following section explains how search can be customized to tailor it to
|
||||
@ -379,12 +458,9 @@ your needs.
|
||||
|
||||
### Query transformation
|
||||
|
||||
[:octicons-file-code-24: Source][23] ·
|
||||
: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][24]:
|
||||
following transformations, which can be customized by [extending the theme]:
|
||||
|
||||
``` ts
|
||||
export function defaultTransform(query: string): string {
|
||||
@ -417,7 +493,7 @@ export function defaultTransform(query: string): string {
|
||||
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][25]:
|
||||
`config` block][overriding blocks]:
|
||||
|
||||
``` html
|
||||
{% extends "base.html" %}
|
||||
@ -437,19 +513,15 @@ 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.
|
||||
|
||||
[23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
|
||||
[24]: ../customization.md#extending-the-theme
|
||||
[25]: ../customization.md#overriding-blocks
|
||||
[extending the theme]: ../customization.md#extending-the-theme
|
||||
[overriding blocks]: ../customization.md#overriding-blocks
|
||||
|
||||
### Custom search
|
||||
|
||||
[:octicons-file-code-24: Source][26] ·
|
||||
:octicons-mortar-board-24: Difficulty: _challenging_
|
||||
|
||||
Material for MkDocs implements search as part of a [web worker][27]. If you
|
||||
Material for MkDocs implements search as part of a [web worker]. 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][24]:
|
||||
`docs` directory and [override the `config` block][overriding blocks]:
|
||||
|
||||
``` html
|
||||
{% block config %}
|
||||
@ -463,12 +535,12 @@ search to an external service, you can add a custom JavaScript file to the
|
||||
```
|
||||
|
||||
Communication with the search worker is implemented using a designated message
|
||||
format using _discriminated unions_, i.e. through the `type` property of the
|
||||
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`][28]
|
||||
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][29]
|
||||
- [:octicons-file-code-24: `SearchMessage`][SearchMessage]
|
||||
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][SearchIndex]
|
||||
|
||||
The sequence and direction of messages is rather intuitive:
|
||||
|
||||
@ -477,7 +549,6 @@ The sequence and direction of messages is rather intuitive:
|
||||
- :octicons-arrow-right-24: `SearchQueryMessage`
|
||||
- :octicons-arrow-left-24: `SearchResultMessage`
|
||||
|
||||
[26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
|
||||
[27]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
|
||||
[28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
|
||||
[29]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
|
||||
[web worker]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
|
||||
[SearchMessage]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
|
||||
[SearchIndex]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
|
||||
|
||||
@ -60,9 +60,10 @@ The following configuration options are available:
|
||||
|
||||
`cards_color`{ #cards-color }
|
||||
|
||||
: :octicons-milestone-24: Default: [primary color][palette.primary] + header
|
||||
text color – This option specifies which colors to use for the background
|
||||
`fill` and foreground `text` when generating the social card:
|
||||
: [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24:
|
||||
Default: [primary color][palette.primary] – This option specifies which
|
||||
colors to use for the background `fill` and foreground `text` when
|
||||
generating the social card:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
|
||||
@ -15,7 +15,7 @@ configured via `mkdocs.yml`.
|
||||
|
||||
### Social links
|
||||
|
||||
[:octicons-tag-24: 1.0.0][Social links support] ·
|
||||
[:octicons-tag-24: 1.0.0][social support] ·
|
||||
:octicons-milestone-24: Default: _none_
|
||||
|
||||
Social links are rendered next to the copyright notice as part of the
|
||||
@ -33,10 +33,10 @@ For each entry, the following settings are available:
|
||||
|
||||
`icon`{ #social-icon }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
|
||||
This field must point to a valid icon path referencing [any icon bundled
|
||||
with the theme][custom icons], or the build will not succeed. Some popular
|
||||
choices:
|
||||
: [:octicons-tag-24: 5.0.0][social.icon support] · :octicons-milestone-24:
|
||||
Default: _none_ · :octicons-alert-24: Required – This field must point to an
|
||||
icon path referencing [any icon bundled with the theme][custom icons], or
|
||||
the build will not succeed. Some popular choices:
|
||||
|
||||
* :fontawesome-brands-behance: – `fontawesome/brands/behance`
|
||||
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
|
||||
@ -49,9 +49,6 @@ For each entry, the following settings are available:
|
||||
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
|
||||
* :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
|
||||
|
||||
[Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
`link`{ #social-link }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
|
||||
@ -78,9 +75,10 @@ For each entry, the following settings are available:
|
||||
|
||||
`name`{ #social-name }
|
||||
|
||||
: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
|
||||
This field is used as the link's `title` attribute and can be set to a
|
||||
discernable name to improve accessibility:
|
||||
: [:octicons-tag-24: 5.1.5][social.name support] · :octicons-milestone-24:
|
||||
Default: _domain name from_ `link`_, if available_ – This field is used as
|
||||
the link's `title` attribute and can be set to a discernable name to
|
||||
improve accessibility:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
@ -90,6 +88,11 @@ For each entry, the following settings are available:
|
||||
name: squidfunk on Twitter
|
||||
```
|
||||
|
||||
[social support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
[social.icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
|
||||
[social.name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.1.5
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
### Copyright notice
|
||||
|
||||
[:octicons-tag-24: 0.1.0][Copyright notice support] ·
|
||||
|
||||
Loading…
Reference in New Issue
Block a user