mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2026-08-01 18:28:48 -04:00
Added site search guide
This commit is contained in:
squidfunk
@@ -1,80 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Awesome pages
|
||||
|
||||
The [mkdocs-awesome-pages-plugin][1] omits the need to specify all pages in the
|
||||
`nav` entry of `mkdocs.yml` and gives you control over page visibility, titles
|
||||
and order on a directory level.
|
||||
|
||||
!!! success "Bundled with the official Docker image"
|
||||
|
||||
This plugin is already installed for your convenience when you use the
|
||||
official [Docker image][2], so the installation step can be skipped. Read
|
||||
the [getting started guide][3] to get up and running with Docker.
|
||||
|
||||
[1]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
|
||||
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[3]: ../getting-started.md#with-docker-recommended
|
||||
|
||||
## Installation
|
||||
|
||||
Install the plugin using `pip`:
|
||||
|
||||
``` sh
|
||||
pip install mkdocs-awesome-pages-plugin
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search # necessary for search to work
|
||||
- awesome-pages
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
If the `nav` entry in `mkdocs.yml` is omitted, MkDocs will automatically include
|
||||
all pages in a specific order. This plugin allows for more fine-grained control
|
||||
on a per-directory basis. In order to configure behavior for a specific
|
||||
directory, create a YAML file named `.pages` in it and set one of the following
|
||||
options.
|
||||
|
||||
### Setting a directory title
|
||||
|
||||
The directory title, which is shown as part of the navigation, can be set with:
|
||||
|
||||
``` yaml
|
||||
title: Lorem ipsum dolor sit amet
|
||||
```
|
||||
|
||||
### Changing the order of pages
|
||||
|
||||
The order of pages and subsections can be configured with:
|
||||
|
||||
``` yaml
|
||||
arrange:
|
||||
- page-1.md
|
||||
- page-2.md
|
||||
- subdirectory
|
||||
```
|
||||
|
||||
### Excluding a directory
|
||||
|
||||
A directory can be hidden (i.e. excluded) with:
|
||||
|
||||
``` yaml
|
||||
hide: true
|
||||
```
|
||||
|
||||
### Collapsing single-page directories
|
||||
|
||||
Directories which contain a single page can be collapsed with:
|
||||
|
||||
``` yaml
|
||||
collapse: true
|
||||
```
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Minification
|
||||
|
||||
The [mkdocs-minify-plugin][1] will minify all `*.html` files generated by
|
||||
`mkdocs build` in a post-processing step, stripping all unnecessary characters
|
||||
to reduce the payload served to the client.
|
||||
|
||||
!!! success "Bundled with the official Docker image"
|
||||
|
||||
This plugin is already installed for your convenience when you use the
|
||||
official [Docker image][2], so the installation step can be skipped. Read
|
||||
the [getting started guide][3] to get up and running with Docker.
|
||||
|
||||
[1]: https://github.com/byrnereese/mkdocs-minify-plugin
|
||||
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[3]: ../getting-started.md#with-docker-recommended
|
||||
|
||||
## Installation
|
||||
|
||||
Install the plugin using `pip`:
|
||||
|
||||
``` sh
|
||||
pip install mkdocs-minify-plugin
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search # necessary for search to work
|
||||
- minify:
|
||||
minify_html: true
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
When enabled, all `*.html` will be minified automatically.
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Revision date
|
||||
|
||||
The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a
|
||||
Markdown file was last updated at the bottom of each page.
|
||||
|
||||
!!! success "Bundled with the official Docker image"
|
||||
|
||||
This plugin is already installed for your convenience when you use the
|
||||
official [Docker image][2], so the installation step can be skipped. Read
|
||||
the [getting started guide][3] to get up and running with Docker.
|
||||
|
||||
[1]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
|
||||
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[3]: ../getting-started.md#with-docker-recommended
|
||||
|
||||
!!! warning "Requirements"
|
||||
|
||||
The date is extracted at the time of the build, so `mkdocs build` must be
|
||||
triggered from within a git repository.
|
||||
|
||||
## Installation
|
||||
|
||||
Install the plugin using `pip`:
|
||||
|
||||
``` sh
|
||||
pip install mkdocs-git-revision-date-localized-plugin
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search # necessary for search to work
|
||||
- git-revision-date-localized
|
||||
```
|
||||
|
||||
Note that the date is printed according to the locale which is determined
|
||||
through the [theme language][2] that was set in `mkdocs.yml`.
|
||||
|
||||
[2]: ../getting-started.md/#language
|
||||
|
||||
### Language
|
||||
|
||||
The language (i.e. locale) is deduced from the `theme.language` option.
|
||||
|
||||
### Format
|
||||
|
||||
> Default: `date`
|
||||
|
||||
To change the date format, set the `type` parameter to one of `date`,
|
||||
`datetime`, `iso_date`, `iso_datetime` or `timeago`, e.g.:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search # necessary for search to work
|
||||
- git-revision-date-localized:
|
||||
type: date
|
||||
```
|
||||
|
||||
The following formats are supported:
|
||||
|
||||
``` gnuplot
|
||||
28 November, 2019 # type: date
|
||||
28 November, 2019 13:57:28 # type: datetime
|
||||
2019-11-28 # type: iso_date
|
||||
2019-11-28 13:57:26 # type: iso_datetime
|
||||
20 hours ago # type: timeago
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
When enabled, the respective date is automatically added at the bottom of each
|
||||
page, e.g.:
|
||||
|
||||
---
|
||||
|
||||
<small>
|
||||
Last updated: 28 November, 2019
|
||||
</small>
|
||||
@@ -1,133 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Search
|
||||
|
||||
The [built-in search plugin][1] provides client-side search inside the browser
|
||||
and is implemented using [lunr.js][2] which includes stemmers for the English
|
||||
language by default, while stemmers for other languages are included with
|
||||
[lunr-languages][3], both of which are integrated with this theme.
|
||||
|
||||
!!! tip "Make search work offline"
|
||||
|
||||
While search will not work for the `file://` protocol, as web workers and
|
||||
the use of `XMLHTTPRequest` are both blocked by modern browsers for security
|
||||
reasons, the [localsearch][4] plugin and @squidfunk's [iframe-worker][5]
|
||||
polyfill add support for cases where this is a mandatory requirement, e.g.,
|
||||
for offline use.
|
||||
|
||||
[1]: https://www.mkdocs.org/user-guide/configuration/#search
|
||||
[2]: https://lunrjs.com
|
||||
[3]: https://github.com/MihaiValentin/lunr-languages
|
||||
[4]: https://github.com/wilhelmer/mkdocs-localsearch
|
||||
[5]: https://github.com/squidfunk/iframe-worker
|
||||
|
||||
## Installation
|
||||
|
||||
The search plugin is a built-in plugin, and thus doesn't need to be installed.
|
||||
|
||||
## Configuration
|
||||
|
||||
Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search
|
||||
```
|
||||
|
||||
### Language
|
||||
|
||||
> Default: best match for `theme.language`, automatically set
|
||||
|
||||
Material for MkDocs selects the (best-)matching stemmer for the given theme
|
||||
language. Multilingual search can be enabled in `mkdocs.yml` by explicitly
|
||||
defining the search language(s):
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
lang:
|
||||
- en
|
||||
- de
|
||||
- ru
|
||||
```
|
||||
|
||||
The following language codes are supported:
|
||||
|
||||
<style>
|
||||
.md-language-list {
|
||||
-webkit-columns: 2;
|
||||
-moz-columns: 2;
|
||||
columns: 2;
|
||||
}
|
||||
.md-language-list li {
|
||||
-webkit-column-break-inside: avoid;
|
||||
page-break-inside: avoid;
|
||||
break-inside: avoid;
|
||||
}
|
||||
</style>
|
||||
<ul class="md-language-list">
|
||||
<li><code>ar</code> / Arabic</li>
|
||||
<li><code>da</code> / Danish</li>
|
||||
<li><code>du</code> / Dutch</li>
|
||||
<li><code>en</code> / English</li>
|
||||
<li><code>fi</code> / Finnish</li>
|
||||
<li><code>fr</code> / French</li>
|
||||
<li><code>de</code> / German</li>
|
||||
<li><code>hu</code> / Hungarian</li>
|
||||
<li><code>it</code> / Italian</li>
|
||||
<li><code>ja</code> / Japanese</li>
|
||||
<li><code>no</code> / Norwegian</li>
|
||||
<li><code>pt</code> / Portuguese</li>
|
||||
<li><code>ro</code> / Romanian</li>
|
||||
<li><code>ru</code> / Russian</li>
|
||||
<li><code>es</code> / Spanish</li>
|
||||
<li><code>sv</code> / Swedish</li>
|
||||
<li><code>th</code> / Thai</li>
|
||||
<li><code>tr</code> / Turkish</li>
|
||||
<li><code>vi</code> / Vietnamese</li>
|
||||
</ul>
|
||||
|
||||
!!! 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.
|
||||
|
||||
### Tokenization
|
||||
|
||||
> Default: `[\s\-]+`
|
||||
|
||||
The separator for tokenization can be customized which makes it possible to
|
||||
index parts of words that are separated by `-` or `.`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
separator: '[\s\-\.]+'
|
||||
```
|
||||
|
||||
### Prebuilding :hatching_chick:
|
||||
|
||||
> Default: `false`
|
||||
|
||||
MkDocs can generate a [prebuilt index][6] of all pages during build time, which
|
||||
provides performance improvements at the cost of more bandwidth. This may be
|
||||
beneficial for large documentation projects that are served with appropriate
|
||||
HTTP headers (e.g. `Content-Encoding: gzip`).
|
||||
|
||||
Material for MkDocs 5 finally brings experimental support for prebuilt indexes
|
||||
which can be enabled by adding the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
prebuild_index: true
|
||||
```
|
||||
|
||||
[6]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
|
||||
|
||||
## Usage
|
||||
|
||||
When enabled, a search bar is shown in the header.
|
||||
Reference in New Issue
Block a user