mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Fixed errors in documentation
This commit is contained in:
parent
49bfe6e572
commit
59e2b9c636
@ -4,7 +4,7 @@ template: overrides/main.html
|
|||||||
|
|
||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
## Sponsor edition
|
## Material for MkDocs Insiders
|
||||||
|
|
||||||
### 1.0.0 <small>_ July 14, 2020</small>
|
### 1.0.0 <small>_ July 14, 2020</small>
|
||||||
|
|
||||||
@ -12,7 +12,7 @@ template: overrides/main.html
|
|||||||
* Added missing query terms to search result
|
* Added missing query terms to search result
|
||||||
* Improved search result relevance and scoring
|
* Improved search result relevance and scoring
|
||||||
|
|
||||||
## Community edition
|
## Material for MkDocs
|
||||||
|
|
||||||
### 5.5.0 <small>_ July 24, 2020</small>
|
### 5.5.0 <small>_ July 24, 2020</small>
|
||||||
|
|
||||||
|
@ -5,7 +5,7 @@ template: overrides/main.html
|
|||||||
# Getting started
|
# Getting started
|
||||||
|
|
||||||
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
|
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
|
||||||
towards (technical) project documentation. If you're familar with Python, you
|
towards (technical) project documentation. If you're familiar with Python, you
|
||||||
can install Material for MkDocs with [`pip`][2], the Python package manager.
|
can install Material for MkDocs with [`pip`][2], the Python package manager.
|
||||||
If not, we recommended using [`docker`][3].
|
If not, we recommended using [`docker`][3].
|
||||||
|
|
||||||
@ -22,16 +22,16 @@ In case you're running into problems, consult the [troubleshooting][4] section.
|
|||||||
|
|
||||||
Material for MkDocs can be installed with `pip`:
|
Material for MkDocs can be installed with `pip`:
|
||||||
|
|
||||||
=== "Community edition"
|
=== "Material for MkDocs"
|
||||||
|
|
||||||
```
|
```
|
||||||
pip install mkdocs-material
|
pip install mkdocs-material
|
||||||
```
|
```
|
||||||
|
|
||||||
=== "Sponsor edition"
|
=== "Material for MkDocs Insiders"
|
||||||
|
|
||||||
``` sh
|
``` sh
|
||||||
pip install git+https://$GH_TOKEN@github.com/squidfunk/mkdocs-material-next.git
|
pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
|
||||||
```
|
```
|
||||||
|
|
||||||
This will automatically install compatible versions of all dependencies:
|
This will automatically install compatible versions of all dependencies:
|
||||||
@ -39,9 +39,9 @@ This will automatically install compatible versions of all dependencies:
|
|||||||
Material for MkDocs always strives to support the latest versions, so there's
|
Material for MkDocs always strives to support the latest versions, so there's
|
||||||
no need to install those packages separately.
|
no need to install those packages separately.
|
||||||
|
|
||||||
Note that in order to install the [sponsor edition][8], you'll need to [become
|
Note that in order to install [__Material for MkDocs Insiders__][8], you'll
|
||||||
a sponsor][9], create a [personal access token][10], and set the `GH_TOKEN`
|
need to [become a sponsor][9], create a [personal access token][10], and set
|
||||||
environment variable to the token's value.
|
the `GH_TOKEN` environment variable to the token's value.
|
||||||
|
|
||||||
[5]: https://python-markdown.github.io/
|
[5]: https://python-markdown.github.io/
|
||||||
[6]: https://pygments.org/
|
[6]: https://pygments.org/
|
||||||
@ -61,7 +61,7 @@ docker pull squidfunk/mkdocs-material
|
|||||||
```
|
```
|
||||||
|
|
||||||
The `mkdocs` executable is provided as an entry point and `serve` is the
|
The `mkdocs` executable is provided as an entry point and `serve` is the
|
||||||
default command. If you're not familar with Docker don't worry, we have you
|
default command. If you're not familiar with Docker don't worry, we have you
|
||||||
covered in the following sections.
|
covered in the following sections.
|
||||||
|
|
||||||
[11]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
[11]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||||
@ -72,16 +72,16 @@ Material for MkDocs can be directly used from [GitHub][12] by cloning the
|
|||||||
repository into a subfolder of your project root which might be useful if you
|
repository into a subfolder of your project root which might be useful if you
|
||||||
want to use the very latest version:
|
want to use the very latest version:
|
||||||
|
|
||||||
=== "Community edition"
|
=== "Material for MkDocs"
|
||||||
|
|
||||||
```
|
```
|
||||||
git clone https://github.com/squidfunk/mkdocs-material.git
|
git clone https://github.com/squidfunk/mkdocs-material.git
|
||||||
```
|
```
|
||||||
|
|
||||||
=== "Sponsor edition"
|
=== "Material for MkDocs Insiders"
|
||||||
|
|
||||||
```
|
```
|
||||||
git clone git@github.com:squidfunk/mkdocs-material-next.git mkdocs-material
|
git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
|
||||||
```
|
```
|
||||||
|
|
||||||
The theme will reside in the folder `mkdocs-material/material`. Note that when
|
The theme will reside in the folder `mkdocs-material/material`. Note that when
|
||||||
@ -91,4 +91,7 @@ cloning from `git`, you must install all required dependencies yourself:
|
|||||||
pip install -r mkdocs-material/requirements.txt
|
pip install -r mkdocs-material/requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Note that in order to install [__Material for MkDocs Insiders__][8], you'll
|
||||||
|
need to [become a sponsor][9].
|
||||||
|
|
||||||
[12]: https://github.com/squidfunk/mkdocs-material
|
[12]: https://github.com/squidfunk/mkdocs-material
|
||||||
|
@ -285,7 +285,7 @@ The `#!python range()` function is used to generate a sequence of numbers.
|
|||||||
|
|
||||||
When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
|
When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||||
Consult the [Python Markdown Extensions][16] documentation to learn about all
|
Consult the [Python Markdown Extensions][16] documentation to learn about all
|
||||||
available short key codes.
|
available key codes.
|
||||||
|
|
||||||
_Example_:
|
_Example_:
|
||||||
|
|
||||||
|
@ -46,13 +46,26 @@ about configuration options.
|
|||||||
[8]: https://octicons.github.com/
|
[8]: https://octicons.github.com/
|
||||||
[9]: ../setup/changing-the-logo-and-icons.md#additional-icons
|
[9]: ../setup/changing-the-logo-and-icons.md#additional-icons
|
||||||
|
|
||||||
|
### Attribute Lists
|
||||||
|
|
||||||
|
The [Attribute List][10] extension, which is part of the standard Markdown
|
||||||
|
library, allows to __add HTML attributes and classes to Markdown elements__,
|
||||||
|
and can be enabled via `mkdocs.yml`
|
||||||
|
|
||||||
|
``` yaml
|
||||||
|
markdown_extensions:
|
||||||
|
- attr_list
|
||||||
|
```
|
||||||
|
|
||||||
|
[10]: https://python-markdown.github.io/extensions/attr_list/
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
### Using emojis
|
### Using emojis
|
||||||
|
|
||||||
Emojis can be integrated in Markdown by putting the shortcode of the emoji
|
Emojis can be integrated in Markdown by putting the shortcode of the emoji
|
||||||
between two colons. If you're using [Twemoji][10] (recommended), you can look up
|
between two colons. If you're using [Twemoji][11] (recommended), you can look up
|
||||||
the shortcodes at [Emojipedia][11].
|
the shortcodes at [Emojipedia][12].
|
||||||
|
|
||||||
_Example_:
|
_Example_:
|
||||||
|
|
||||||
@ -64,12 +77,12 @@ _Result_:
|
|||||||
|
|
||||||
:smile:
|
:smile:
|
||||||
|
|
||||||
[10]: https://twemoji.twitter.com/
|
[11]: https://twemoji.twitter.com/
|
||||||
[11]: https://emojipedia.org/twitter/
|
[12]: https://emojipedia.org/twitter/
|
||||||
|
|
||||||
### Using icons
|
### Using icons
|
||||||
|
|
||||||
When [Emoji][12] is enabled, icons can be used similar to emojis, by referencing
|
When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing
|
||||||
a valid path to any icon bundled with the theme, which are located in the
|
a valid path to any icon bundled with the theme, which are located in the
|
||||||
[`.icons`][1] directory, and replacing `/` with `-`:
|
[`.icons`][1] directory, and replacing `/` with `-`:
|
||||||
|
|
||||||
@ -83,11 +96,15 @@ _Example_:
|
|||||||
|
|
||||||
_Result_:
|
_Result_:
|
||||||
|
|
||||||
* :material-account-circle: – [`.icons/material/account-circle.svg`][13]
|
* :material-account-circle: – [`.icons/material/account-circle.svg`][14]
|
||||||
* :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][14]
|
* :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
|
||||||
* :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][15]
|
* :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16]
|
||||||
|
|
||||||
[12]: #emoji
|
[13]: #emoji
|
||||||
[13]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
|
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
|
||||||
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
|
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
|
||||||
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg
|
[16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg
|
||||||
|
|
||||||
|
### Using colored icons
|
||||||
|
|
||||||
|
### Using animated icons
|
||||||
|
@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
template: overrides/main.html
|
template: overrides/main.html
|
||||||
|
disqus: mkdocs material
|
||||||
---
|
---
|
||||||
|
|
||||||
# Adding a comment system
|
# Adding a comment system
|
||||||
|
@ -6,7 +6,7 @@ template: overrides/main.html
|
|||||||
|
|
||||||
If your documentation is related to source code, Material for MkDocs provides
|
If your documentation is related to source code, Material for MkDocs provides
|
||||||
the ability to display information to the project's repository as part of the
|
the ability to display information to the project's repository as part of the
|
||||||
static site, including statistics like stars and forks. Furthermore, certain
|
static site, including statistics like stars and forks. Furthermore, individual
|
||||||
documents can be linked to specific source files.
|
documents can be linked to specific source files.
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
@ -4,7 +4,7 @@ template: overrides/main.html
|
|||||||
|
|
||||||
# Adding social links
|
# Adding social links
|
||||||
|
|
||||||
The footer of your project documentation is a good place to add links to
|
The footer of your project documentation is a great place to add links to
|
||||||
websites or platforms you or your company are using as additional marketing
|
websites or platforms you or your company are using as additional marketing
|
||||||
channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" },
|
channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" },
|
||||||
:fontawesome-brands-twitter:{: style="color: #1DA1F2" } or
|
:fontawesome-brands-twitter:{: style="color: #1DA1F2" } or
|
||||||
|
@ -4,7 +4,7 @@ template: overrides/main.html
|
|||||||
|
|
||||||
# Changing the colors
|
# Changing the colors
|
||||||
|
|
||||||
As any good Material Design implementation, Material for MkDocs supports
|
As any proper Material Design implementation, Material for MkDocs supports
|
||||||
Google's original [color palette][1], which can be easily configured through
|
Google's original [color palette][1], which can be easily configured through
|
||||||
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
|
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
|
||||||
fit your brand's identity by using [CSS variables][2].
|
fit your brand's identity by using [CSS variables][2].
|
||||||
@ -28,7 +28,7 @@ theme:
|
|||||||
scheme: default
|
scheme: default
|
||||||
```
|
```
|
||||||
|
|
||||||
:material-cursor-default-click-outline: click on a tile to change the color
|
:material-cursor-default-click-outline: Click on a tile to change the color
|
||||||
scheme:
|
scheme:
|
||||||
|
|
||||||
<div class="tx-switch">
|
<div class="tx-switch">
|
||||||
@ -74,7 +74,7 @@ theme:
|
|||||||
primary: indigo
|
primary: indigo
|
||||||
```
|
```
|
||||||
|
|
||||||
:material-cursor-default-click-outline: click on a tile to change the primary
|
:material-cursor-default-click-outline: Click on a tile to change the primary
|
||||||
color:
|
color:
|
||||||
|
|
||||||
<div class="tx-switch">
|
<div class="tx-switch">
|
||||||
@ -121,7 +121,7 @@ color:
|
|||||||
|
|
||||||
The _accent color_ is used to denote elements that can be interacted with, e.g.
|
The _accent color_ is used to denote elements that can be interacted with, e.g.
|
||||||
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
|
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
|
||||||
chosing a valid color name:
|
choosing a valid color name:
|
||||||
|
|
||||||
``` yaml
|
``` yaml
|
||||||
theme:
|
theme:
|
||||||
@ -129,7 +129,7 @@ theme:
|
|||||||
accent: indigo
|
accent: indigo
|
||||||
```
|
```
|
||||||
|
|
||||||
:material-cursor-default-click-outline: click on a tile to change the accent
|
:material-cursor-default-click-outline: Click on a tile to change the accent
|
||||||
color:
|
color:
|
||||||
|
|
||||||
<style>
|
<style>
|
||||||
@ -178,7 +178,7 @@ color:
|
|||||||
|
|
||||||
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
|
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
|
||||||
= __714__ combinations, it's impossible to ensure that all configurations
|
= __714__ combinations, it's impossible to ensure that all configurations
|
||||||
provide a good user experience (e.g. _yellow on light background_), so make
|
provide a good user experience (e.g. _yellow on light background_). Make
|
||||||
sure that the color combination of your choosing provides enough contrast
|
sure that the color combination of your choosing provides enough contrast
|
||||||
and tweak CSS variables where necessary.
|
and tweak CSS variables where necessary.
|
||||||
|
|
||||||
|
@ -76,7 +76,7 @@ theme:
|
|||||||
[:octicons-file-code-24: Source][2] ·
|
[:octicons-file-code-24: Source][2] ·
|
||||||
:octicons-mortar-board-24: Difficulty: _easy_
|
:octicons-mortar-board-24: Difficulty: _easy_
|
||||||
|
|
||||||
If you want to load an (additional) font from another destination, or override
|
If you want to load an (additional) font from another or override
|
||||||
the fallback font, you can use an [additional stylesheet][8] to add the
|
the fallback font, you can use an [additional stylesheet][8] to add the
|
||||||
corresponding `@font-face` definition:
|
corresponding `@font-face` definition:
|
||||||
|
|
||||||
|
@ -6,7 +6,8 @@ template: overrides/main.html
|
|||||||
|
|
||||||
Material for MkDocs supports internationalization (i18n) and provides
|
Material for MkDocs supports internationalization (i18n) and provides
|
||||||
translations for template variables and labels in 40+ languages. Additionally,
|
translations for template variables and labels in 40+ languages. Additionally,
|
||||||
search can be configured to use a language-specific stemmer (if available).
|
the site search can be configured to use a language-specific stemmer (if
|
||||||
|
available).
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
@ -105,7 +106,7 @@ theme:
|
|||||||
direction: ltr
|
direction: ltr
|
||||||
```
|
```
|
||||||
|
|
||||||
:material-cursor-default-click-outline: click on a tile to change the
|
:material-cursor-default-click-outline: Click on a tile to change the
|
||||||
directionality:
|
directionality:
|
||||||
|
|
||||||
<div class="tx-switch">
|
<div class="tx-switch">
|
||||||
|
@ -7,7 +7,7 @@ template: overrides/main.html
|
|||||||
When installing Material for MkDocs, you immediately get access to _over 7.000
|
When installing Material for MkDocs, you immediately get access to _over 7.000
|
||||||
icons_ ready to be used for customization of specific parts of the theme and/or
|
icons_ ready to be used for customization of specific parts of the theme and/or
|
||||||
when writing your documentation in Markdown. Not enough? You can also [add
|
when writing your documentation in Markdown. Not enough? You can also [add
|
||||||
additional icons][1] with very little effort.
|
additional icons][1] with minimal effort.
|
||||||
|
|
||||||
[1]: #additional-icons
|
[1]: #additional-icons
|
||||||
|
|
||||||
@ -92,7 +92,7 @@ If you want to add [additional icons][1], read on.
|
|||||||
[:octicons-file-code-24: Source][3] ·
|
[:octicons-file-code-24: Source][3] ·
|
||||||
:octicons-mortar-board-24: Difficulty: _moderate_
|
:octicons-mortar-board-24: Difficulty: _moderate_
|
||||||
|
|
||||||
In order to add additional icons, [extend the theme][11] and create a folder
|
In order to add additional icons, [extend the theme][11], and create a folder
|
||||||
named `.icons` in the [`custom_dir`][12] you want to use for overrides. Next,
|
named `.icons` in the [`custom_dir`][12] you want to use for overrides. Next,
|
||||||
add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you
|
add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you
|
||||||
downloaded and unpacked the [Bootstrap][13] icon set, and want to add it to
|
downloaded and unpacked the [Bootstrap][13] icon set, and want to add it to
|
||||||
|
@ -27,10 +27,10 @@ theme:
|
|||||||
```
|
```
|
||||||
|
|
||||||
The resulting page is parsed and injected and all event handlers and components
|
The resulting page is parsed and injected and all event handlers and components
|
||||||
are automatically rebound. This means that __Material for MkDocs behaves like a
|
are rebound automatically. This means that __Material for MkDocs behaves like a
|
||||||
Single Page Application__, which is especially useful for large documentation
|
Single Page Application__, which is especially useful for large documentation
|
||||||
sites that come with a huge search index, as the search index will now remain
|
sites that come with a massive search index, as the search index will now
|
||||||
intact in-between document switches.
|
remain intact in-between document switches.
|
||||||
|
|
||||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
|
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
|
||||||
[2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
[2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
|
||||||
@ -202,9 +202,9 @@ to navigate your project documentation via keyboard. There're two modes:
|
|||||||
|
|
||||||
`global`{: #global }
|
`global`{: #global }
|
||||||
|
|
||||||
: This mode is the active when _search is not active_, i.e. when there's no
|
: This mode is active when _search is not focussed_ and when there's no other
|
||||||
other focussed element that is suceptible to keyboard input. The following
|
focussed element that is susceptible to keyboard input. The following keys
|
||||||
keys are bound:
|
are bound:
|
||||||
|
|
||||||
- ++f++ , ++s++ , ++slash++ : open search dialog
|
- ++f++ , ++s++ , ++slash++ : open search dialog
|
||||||
- ++p++ , ++comma++ : go to previous page
|
- ++p++ , ++comma++ : go to previous page
|
||||||
@ -224,7 +224,7 @@ app.keyboard$.subscribe(key => {
|
|||||||
```
|
```
|
||||||
|
|
||||||
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
|
The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
|
||||||
on the underlying event, so the key press will not propagate further and touch
|
on the underlying event, so the keypress will not propagate further and touch
|
||||||
other event listeners.
|
other event listeners.
|
||||||
|
|
||||||
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
||||||
|
@ -4,7 +4,7 @@ template: overrides/main.html
|
|||||||
|
|
||||||
# Setting up site analytics
|
# Setting up site analytics
|
||||||
|
|
||||||
As with any other service that is offered on the web, understanding how your
|
As with any other service offered on the web, understanding how your project
|
||||||
documentation is actually used can be an essential success factor. While
|
documentation is actually used can be an essential success factor. While
|
||||||
Material for MkDocs natively integrates with [Google Analytics][1], [other
|
Material for MkDocs natively integrates with [Google Analytics][1], [other
|
||||||
analytics services][2] can be used, too.
|
analytics services][2] can be used, too.
|
||||||
@ -19,8 +19,8 @@ analytics services][2] can be used, too.
|
|||||||
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
|
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
|
||||||
|
|
||||||
After heading over to your [Google Analytics][1] account to [create a new
|
After heading over to your [Google Analytics][1] account to [create a new
|
||||||
property][4] in order to obtain a new tracking id of the form `UA-XXXXXXXX-X`,
|
property][4] in order to obtain a unique tracking id of the form
|
||||||
add it to `mkdocs.yml`:
|
`UA-XXXXXXXX-X`, add it to `mkdocs.yml`:
|
||||||
|
|
||||||
``` yaml
|
``` yaml
|
||||||
google_analytics:
|
google_analytics:
|
||||||
@ -33,7 +33,7 @@ google_analytics:
|
|||||||
|
|
||||||
#### Site search tracking
|
#### Site search tracking
|
||||||
|
|
||||||
Besides basic page views, _site search_ can also be tracked to better understand
|
Besides basic page views, _site search_ can also be tracked to understand better
|
||||||
how people use your documentation and what they expect to find. To enable
|
how people use your documentation and what they expect to find. To enable
|
||||||
search tracking:
|
search tracking:
|
||||||
|
|
||||||
@ -79,7 +79,7 @@ app.location$.subscribe(function(url) {
|
|||||||
```
|
```
|
||||||
|
|
||||||
Note that this must be integrated with [additional JavaScript][8], and cannot be
|
Note that this must be integrated with [additional JavaScript][8], and cannot be
|
||||||
included as part of the `analytics` block, which is included in the `head` of
|
included as part of the `analytics` block, as it is included in the `head` of
|
||||||
the document.
|
the document.
|
||||||
|
|
||||||
[7]: setting-up-navigation.md#instant-loading
|
[7]: setting-up-navigation.md#instant-loading
|
||||||
|
@ -4,10 +4,10 @@ template: overrides/main.html
|
|||||||
|
|
||||||
# Setting up site search
|
# Setting up site search
|
||||||
|
|
||||||
Material for MkDocs provides a great, client-side search implementation,
|
Material for MkDocs provides an excellent, client-side search implementation,
|
||||||
omitting the need for the integration of third-party services, which might
|
omitting the need for the integration of third-party services, which might
|
||||||
violate data privacy regulations. Furthermore, with some effort, search can
|
violate data privacy regulations. Moreover, with some effort, search can be
|
||||||
be made available [offline][1].
|
made available [offline][1].
|
||||||
|
|
||||||
[1]: #offline-search
|
[1]: #offline-search
|
||||||
|
|
||||||
@ -35,7 +35,7 @@ The following options are supported:
|
|||||||
: :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][5].
|
||||||
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 overriden, e.g. to support multiple
|
[site language][6], but it may be overridden, e.g. to support multiple
|
||||||
languages:
|
languages:
|
||||||
|
|
||||||
=== "A single language"
|
=== "A single language"
|
||||||
@ -80,8 +80,8 @@ The following options are supported:
|
|||||||
<li><code>vi</code> – Vietnamese</li>
|
<li><code>vi</code> – Vietnamese</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
_Material for MkDocs also tries to support languages which are not part of
|
_Material for MkDocs also tries to support languages that are not part of
|
||||||
this list, by automatically chosing the best-matching stemmer_.
|
this list by choosing the stemmer yielding the best result automatically_.
|
||||||
|
|
||||||
!!! warning "Only specify the languages you really need"
|
!!! warning "Only specify the languages you really need"
|
||||||
|
|
||||||
@ -92,9 +92,9 @@ The following options are supported:
|
|||||||
`separator`{: #separator }
|
`separator`{: #separator }
|
||||||
|
|
||||||
: :octicons-milestone-24: Default: _automatically set_ – The separator for
|
: :octicons-milestone-24: Default: _automatically set_ – The separator for
|
||||||
indexing and query tokenization can be customized, which makes it possible
|
indexing and query tokenization can be customized, making it possible to
|
||||||
to index parts of words that are separated by other characters than
|
index parts of words separated by other characters than whitespace and `-`,
|
||||||
whitespace and `-`, e.g. by including `.`:
|
e.g. by including `.`:
|
||||||
|
|
||||||
``` yaml
|
``` yaml
|
||||||
plugins:
|
plugins:
|
||||||
@ -151,10 +151,11 @@ For setup instructions, refer to the [official documentation][11].
|
|||||||
|
|
||||||
The search implementation of Material for MkDocs is probably its most
|
The search implementation of Material for MkDocs is probably its most
|
||||||
sophisticated feature, as it tries to balance a _great typeahead experience_,
|
sophisticated feature, as it tries to balance a _great typeahead experience_,
|
||||||
_good performance_, _accessibility_ and a result list that is _easy to scan_.
|
_good performance_, _accessibility_, and a result list that is _easy to scan_.
|
||||||
This is where it deviates from other themes.
|
This is where Material for MkDocs deviates from other themes.
|
||||||
|
|
||||||
This section explains how search can be customized to tailor it to your needs.
|
The following section explains how search can be customized to tailor it to
|
||||||
|
your needs.
|
||||||
|
|
||||||
### Query transformation
|
### Query transformation
|
||||||
|
|
||||||
|
@ -4,10 +4,10 @@ template: overrides/main.html
|
|||||||
|
|
||||||
# <span hidden>Sponsorship</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart }
|
# <span hidden>Sponsorship</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart }
|
||||||
|
|
||||||
Material for MkDocs uses the [sponsorware][1] release strategy, which means that
|
Material for MkDocs uses the [sponsorware][1] release strategy, which means
|
||||||
__new features are first exclusively released to sponsors__. Read on to learn
|
that _new features are first exclusively released to sponsors_ as part of
|
||||||
[how sponsorship works][2] and how you can [become a sponsor][3] to enjoy the
|
__Material for MkDocs Insiders__. Read on to learn [how sponsorship works][2],
|
||||||
latest features before everybody else.
|
and how you can [become a sponsor][3].
|
||||||
|
|
||||||
[1]: https://github.com/sponsorware/docs
|
[1]: https://github.com/sponsorware/docs
|
||||||
[2]: #how-sponsorship-works
|
[2]: #how-sponsorship-works
|
||||||
@ -15,45 +15,38 @@ latest features before everybody else.
|
|||||||
|
|
||||||
## How sponsorship works
|
## How sponsorship works
|
||||||
|
|
||||||
__Material for MkDocs is available as a community edition and sponsor edition__.
|
New features will first land in Material for MkDocs Insiders, which means that
|
||||||
|
_sponsors will have access immediately_. Every feature is tied to a funding
|
||||||
|
goal in monthly subscriptions. If a funding goal is hit, the features that are
|
||||||
|
tied to it are merged back into Material for MkDocs and released for general
|
||||||
|
availability. Bugfixes will always be released simultaneously in both editions.
|
||||||
|
|
||||||
New features will first land in the _sponsor edition_, which means that sponsors
|
See the [roadmap][4] for a list of already available and upcoming features, and
|
||||||
will have access immediately. Every feature is tied to a funding goal in monthly
|
for demonstration purposes, [the official docs][5] built with Material for
|
||||||
subscriptions. If this funding goal is hit, the feature is merged into the
|
MkDocs Insiders.
|
||||||
_community edition_ and released to the public to be generally available. Bugs
|
|
||||||
will be fixed in the community edition and merged back into the sponsor edition:
|
|
||||||
|
|
||||||
- :material-bug-check: Bugfixes: _community edition_ :material-arrow-right:
|
|
||||||
_sponsor edition_
|
|
||||||
- :material-new-box: Features: _community edition_ :material-arrow-left:
|
|
||||||
_sponsor edition_
|
|
||||||
|
|
||||||
See the [roadmap][4] for a list of available and upcoming features of the
|
|
||||||
_sponsor edition_, and for demonstration purposes, [__the official docs built
|
|
||||||
with the sponsor edition__][5].
|
|
||||||
|
|
||||||
[4]: #roadmap
|
[4]: #roadmap
|
||||||
[5]: https://squidfunk.github.io/mkdocs-material-next/
|
[5]: https://squidfunk.github.io/mkdocs-material-next/
|
||||||
|
|
||||||
## How to become a sponsor
|
## How to become a sponsor
|
||||||
|
|
||||||
You've decided to become a sponsor? Great! You're just __three easy steps__ away
|
So you've decided to become a sponsor? Great! You're just __three easy steps__
|
||||||
from enjoying the latest features of Material for MkDocs. Complete the following
|
away from enjoying the latest features of Material for MkDocs Insiders.
|
||||||
steps and you're in:
|
Complete the following steps and you're in:
|
||||||
|
|
||||||
- Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive
|
- Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive
|
||||||
access to squidfunk's sponsorware, which is any tier above $10/month. Select
|
access to squidfunk's sponsorware, which is _any tier above $10/month_. Select
|
||||||
the tier and complete the checkout.
|
the tier and complete the checkout.
|
||||||
- Within 24 hours, you will be added as a collaborator to a private GitHub
|
- Within 24 hours, you will become a collaborator of the private Material for
|
||||||
repository, which contains a fork of Material for MkDocs with [brand new and
|
MkDocs Insiders GitHub repository, a fork of Material for MkDocs with
|
||||||
exclusive features][7].
|
[brand new and exclusive features][7].
|
||||||
- Create a [personal access token][8], which allows installing the _sponsor
|
- Create a [personal access token][8], which allows installing Material for
|
||||||
edition_ of Material for MkDocs from any destination, including other CI
|
MkDocs Insiders from any destination, including other CI providers like
|
||||||
providers like [GitLab][9] or [Bitbucket][10].
|
[GitLab][9] or [Bitbucket][10].
|
||||||
|
|
||||||
__Congratulations! :partying_face: You're now officially a sponsor and can use
|
__Congratulations! :partying_face: You're now officially a sponsor and will
|
||||||
the sponsor edition until you decide to cancel your monthly subscription, which
|
get updates for Material for MkDocs Insiders, until you decide to cancel your
|
||||||
you're free to do at any time.__
|
monthly subscription, which you can do at any time.__
|
||||||
|
|
||||||
[6]: https://github.com/sponsors/squidfunk
|
[6]: https://github.com/sponsors/squidfunk
|
||||||
[7]: #roadmap
|
[7]: #roadmap
|
||||||
@ -64,8 +57,8 @@ you're free to do at any time.__
|
|||||||
## Roadmap
|
## Roadmap
|
||||||
|
|
||||||
The following list of funding goals – named after varieties of chili peppers
|
The following list of funding goals – named after varieties of chili peppers
|
||||||
[I'm growing on my balcony][11] – shows, which features are already part of the
|
[I'm growing on my balcony][11] – shows which features are already available
|
||||||
sponsor edition or yet to come.
|
in Material for MkDocs Insiders.
|
||||||
|
|
||||||
[11]: https://www.instagram.com/squidfunk/
|
[11]: https://www.instagram.com/squidfunk/
|
||||||
|
|
||||||
@ -74,46 +67,73 @@ sponsor edition or yet to come.
|
|||||||
[:octicons-fire-24: Funding goal: __$500__][6] ·
|
[:octicons-fire-24: Funding goal: __$500__][6] ·
|
||||||
:octicons-lock-24: Status: _exclusively available_
|
:octicons-lock-24: Status: _exclusively available_
|
||||||
|
|
||||||
Improve search UI and UX to show relevant results more prominently, show missing
|
New features and improvements for _search_, including:
|
||||||
terms that were not found on a specific page and highlight terms found when
|
|
||||||
following a search result.
|
|
||||||
|
|
||||||
- [x] #1790 – Added grouping of search results
|
- [x] Improved search result grouping (pages + headings)
|
||||||
- [x] #1799 – Added missing query terms to search result
|
- [x] Improved search result relevance and scoring
|
||||||
- [x] #1799 – Improved search result relevance and scoring
|
- [x] Display of missing query terms in search results
|
||||||
- [ ] TBD – Improved search result summaries
|
- [ ] Highlighting of query terms on followed page
|
||||||
- [ ] TBD – Added highlighting of query terms on target pages
|
- [ ] Improved search result summaries
|
||||||
|
- [ ] ... more to come
|
||||||
|
|
||||||
|
### Prairie Fire
|
||||||
|
|
||||||
|
[:octicons-fire-24: Funding goal: __$1,000__][6] ·
|
||||||
|
:octicons-lock-24: Status: _pending_
|
||||||
|
|
||||||
|
New features and improvements for _table of contents_, including:
|
||||||
|
|
||||||
|
- [ ] Table of contents can be moved into navigation for more space
|
||||||
|
- [ ] Table of contents shows which sections have search results
|
||||||
|
- [ ] Better support for wide screens, i.e. more horizontal space
|
||||||
|
- [ ] ... more to come
|
||||||
|
|
||||||
### Bhut Jolokia
|
### Bhut Jolokia
|
||||||
|
|
||||||
[:octicons-fire-24: Funding goal: __$1,500__][6] ·
|
[:octicons-fire-24: Funding goal: __$1,500__][6] ·
|
||||||
:octicons-lock-24: Status: _pending_
|
:octicons-lock-24: Status: _pending_
|
||||||
|
|
||||||
Add native support to Material for MkDocs to build and deploy multiple versions
|
New features and improvements for _hosting multiple versions_, including:
|
||||||
of a single documentation project, with the help of a plugin.
|
|
||||||
|
- [ ] Support for multiple languages of documents
|
||||||
|
- [ ] Support for multiple versions of documents
|
||||||
|
- [ ] Support for one or more management plugins
|
||||||
|
- [ ] ... more to come
|
||||||
|
|
||||||
|
### Black Pearl
|
||||||
|
|
||||||
|
[:octicons-fire-24: Funding goal: __$2,000__][6] ·
|
||||||
|
:octicons-lock-24: Status: _pending_
|
||||||
|
|
||||||
|
New features and improvements for _user preferences_, including:
|
||||||
|
|
||||||
|
- [ ] Support for user-toggleable themes
|
||||||
|
- [ ] Display last searches when search is empty
|
||||||
|
- [ ] ... more to come
|
||||||
|
|
||||||
### Caribbean Red
|
### Caribbean Red
|
||||||
|
|
||||||
[:octicons-fire-24: Funding goal: __$3,000__][6] ·
|
[:octicons-fire-24: Funding goal: __$3,000__][6] ·
|
||||||
:octicons-lock-24: Status: _pending_
|
:octicons-lock-24: Status: _pending_
|
||||||
|
|
||||||
Add an alternative, completely different _vertical layout_, optimized to read
|
Alternative, completely different _vertical layout_, optimized to read
|
||||||
documentation and code side-by-side, e.g. for the documentation of APIs.
|
documentation and code side-by-side, e.g. for the documentation of APIs with
|
||||||
|
the same functionality as Material for MkDocs.
|
||||||
|
|
||||||
## Terms
|
## Terms
|
||||||
|
|
||||||
Regardless of whether you're an individual or a company, you may use the
|
Whether you're an individual or a company, you may use _Material for MkDocs
|
||||||
_sponsor edition_ exactly under the same terms as the _community edition_,
|
Insiders_ precisely under the same terms as _Material for MkDocs_, which are
|
||||||
which are given by the [MIT license][12]. However, we kindly ask you to respect
|
given by the [MIT license][12]. However, we kindly ask you to respect
|
||||||
the following guidelines:
|
the following guidelines:
|
||||||
|
|
||||||
- Please __don't distribute the source code__ from the _sponsor edition_.
|
- Please __don't distribute the source code__ from Material for MkDocs Insiders.
|
||||||
You may freely use it for public, private or commercial projects, fork it,
|
You may freely use it for public, private or commercial projects, fork it,
|
||||||
mirror it, do whatever you want with it, as long as you're not releasing the
|
mirror it, do whatever you want with it, but please don't release the source
|
||||||
source code, as this would cannibalize the sponsorware model.
|
code, as it would cannibalize the sponsorware strategy.
|
||||||
|
|
||||||
- If you cancel your subscription, you're removed as a collaborator and will not
|
- If you cancel your subscription, you're removed as a collaborator and will
|
||||||
receive future updates of the sponsor edition. However, you may continue to
|
miss out on future updates of Material for MkDocs Insiders. However, you may
|
||||||
__use the latest version__ that's available to you __as long as you like__.
|
__use the latest version__ that's available to you __as long as you like__.
|
||||||
Just remember that __[GitHub deletes private forks][13]__.
|
Just remember that __[GitHub deletes private forks][13]__.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user