mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Added site search guide
This commit is contained in:
squidfunk
parent
8602969890
commit
fed4146fa0
@ -10,7 +10,7 @@ mkdocs-material-5.3.3 (2020-06-24)
|
|||||||
|
|
||||||
mkdocs-material-5.3.2 (2020-06-21)
|
mkdocs-material-5.3.2 (2020-06-21)
|
||||||
|
|
||||||
* Improved search type-ahead experience with non-Latin characters
|
* Improved search typeahead experience with non-Latin characters
|
||||||
* Fixed #1753: Japanese search doesn't work anymore
|
* Fixed #1753: Japanese search doesn't work anymore
|
||||||
|
|
||||||
mkdocs-material-5.3.1 (2020-06-20)
|
mkdocs-material-5.3.1 (2020-06-20)
|
||||||
|
|||||||
@ -66,27 +66,29 @@ icons and much more:
|
|||||||
* [Changing colors][3]
|
* [Changing colors][3]
|
||||||
* [Changing the fonts][4]
|
* [Changing the fonts][4]
|
||||||
* [Changing the language][5]
|
* [Changing the language][5]
|
||||||
* [Navigation][6]
|
* [Setting up navigation][6]
|
||||||
* [Syntax highlighting][7]
|
* [Setting up site search][7]
|
||||||
* [Adding a landing page][8]
|
* [Adding a git repository][8]
|
||||||
* [Adding an announcement bar][9]
|
* [Adding icons and emojis][9]
|
||||||
* [Adding icons and emojis][10]
|
* [Adding footer links][10]
|
||||||
* [Adding footer links][11]
|
* [Adding site analytics][11]
|
||||||
* [Adding site analytics][12]
|
* [Adding a comment system][12]
|
||||||
* [Adding a comment system][13]
|
* [Adding an announcement bar][13]
|
||||||
|
* [Adding a landing page][14]
|
||||||
|
|
||||||
[2]: getting-started.md#installation
|
[2]: getting-started.md#installation
|
||||||
[3]: guides/changing-colors.md
|
[3]: guides/changing-colors.md
|
||||||
[4]: guides/changing-the-fonts.md
|
[4]: guides/changing-the-fonts.md
|
||||||
[5]: guides/changing-the-language.md
|
[5]: guides/changing-the-language.md
|
||||||
[6]: guides/navigation.md
|
[6]: guides/setting-up-navigation.md
|
||||||
[7]: guides/syntax-highlighting.md
|
[7]: guides/setting-up-site-search.md
|
||||||
[8]: guides/adding-a-landing-page.md
|
[8]: guides/adding-a-git-repository.md
|
||||||
[9]: guides/adding-an-announcement-bar.md
|
[9]: guides/adding-icons-and-emojis.md
|
||||||
[10]: guides/adding-icons-and-emojis.md
|
[10]: guides/adding-footer-links.md
|
||||||
[11]: guides/adding-footer-links.md
|
[11]: guides/adding-site-analytics.md
|
||||||
[12]: guides/adding-site-analytics.md
|
[12]: guides/adding-a-comment-system.md
|
||||||
[13]: guides/adding-a-comment-system.md
|
[13]: guides/adding-an-announcement-bar.md
|
||||||
|
[14]: guides/adding-a-landing-page.md
|
||||||
|
|
||||||
## Previewing as you write
|
## Previewing as you write
|
||||||
|
|
||||||
@ -112,12 +114,12 @@ If you're running Material for MkDocs from within Docker, use:
|
|||||||
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
|
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
|
||||||
```
|
```
|
||||||
|
|
||||||
Point your browser to [localhost:8000][14] and you should see:
|
Point your browser to [localhost:8000][15] and you should see:
|
||||||
|
|
||||||
[![Creating your site][15]][14]
|
[![Creating your site][16]][15]
|
||||||
|
|
||||||
[14]: http://localhost:8000
|
[15]: http://localhost:8000
|
||||||
[15]: assets/guides/creating-your-site.png
|
[16]: assets/guides/creating-your-site.png
|
||||||
|
|
||||||
## Building your site
|
## Building your site
|
||||||
|
|
||||||
@ -130,8 +132,8 @@ mkdocs build
|
|||||||
|
|
||||||
The contents of this directory make up your project documentation. There's no
|
The contents of this directory make up your project documentation. There's no
|
||||||
need for operating a database or server, as it is completely self-contained.
|
need for operating a database or server, as it is completely self-contained.
|
||||||
The site can be hosted on [GitHub Pages][16], [GitLab Pages][17], a CDN of your
|
The site can be hosted on [GitHub Pages][17], [GitLab Pages][18], a CDN of your
|
||||||
choice or your private web space.
|
choice or your private web space.
|
||||||
|
|
||||||
[16]: publishing-your-site.md#github-pages
|
[17]: publishing-your-site.md#github-pages
|
||||||
[17]: publishing-your-site.md#gitlab-pages
|
[18]: publishing-your-site.md#gitlab-pages
|
||||||
|
|||||||
@ -101,7 +101,7 @@ The directory layout of the theme is as follows:
|
|||||||
│ ├─ javascripts/ # JavaScript
|
│ ├─ javascripts/ # JavaScript
|
||||||
│ └─ stylesheets/ # Stylesheets
|
│ └─ stylesheets/ # Stylesheets
|
||||||
├─ partials/
|
├─ partials/
|
||||||
│ ├─ integrations/ # 3rd-party integrations
|
│ ├─ integrations/ # Third-party integrations
|
||||||
│ ├─ language/ # Localized languages
|
│ ├─ language/ # Localized languages
|
||||||
│ ├─ footer.html # Footer bar
|
│ ├─ footer.html # Footer bar
|
||||||
│ ├─ header.html # Header bar
|
│ ├─ header.html # Header bar
|
||||||
|
|||||||
@ -1,459 +0,0 @@
|
|||||||
---
|
|
||||||
template: overrides/main.html
|
|
||||||
---
|
|
||||||
|
|
||||||
# Admonition
|
|
||||||
|
|
||||||
[Admonition][1] is an extension included in the standard Markdown library that
|
|
||||||
makes it possible to add block-styled side content to your documentation, e.g.
|
|
||||||
summaries, notes, hints or warnings.
|
|
||||||
|
|
||||||
[1]: https://python-markdown.github.io/extensions/admonition/
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Add the following lines to `mkdocs.yml`:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
markdown_extensions:
|
|
||||||
- admonition
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
Admonitions follow a simple syntax: every block is started with `!!!`, followed
|
|
||||||
by a single keyword which is used as the [type qualifier][2] of the block. The
|
|
||||||
content of the block then follows on the next line, indented by four spaces.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! note
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
[2]: #types
|
|
||||||
|
|
||||||
### Changing the title
|
|
||||||
|
|
||||||
By default, the Admonition title will equal the type qualifier in titlecase.
|
|
||||||
However, it can be changed by adding a quoted string after the type qualifier.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! note "Phasellus posuere in sem ut cursus"
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! note "Phasellus posuere in sem ut cursus"
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
### Removing the title
|
|
||||||
|
|
||||||
Similar to [changing the title][3], the icon and title can be omitted by
|
|
||||||
providing an empty string after the type qualifier:
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! note ""
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! note ""
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
[3]: #changing-the-title
|
|
||||||
|
|
||||||
### Embedded content
|
|
||||||
|
|
||||||
Admonitions can contain all kinds of text content, including headlines, lists,
|
|
||||||
paragraphs and other blocks – except code blocks, because the parser from the
|
|
||||||
standard Markdown library does not account for those.
|
|
||||||
|
|
||||||
The [PyMdown Extensions][4] package adds an extension called [SuperFences][5],
|
|
||||||
which makes it possible to nest code blocks within other blocks, respectively
|
|
||||||
Admonition blocks.
|
|
||||||
|
|
||||||
[4]: https://facelessuser.github.io/pymdown-extensions
|
|
||||||
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
``` mysql
|
|
||||||
SELECT
|
|
||||||
Employees.EmployeeID,
|
|
||||||
Employees.Name,
|
|
||||||
Employees.Salary,
|
|
||||||
Manager.Name AS Manager
|
|
||||||
FROM
|
|
||||||
Employees
|
|
||||||
LEFT JOIN
|
|
||||||
Employees AS Manager
|
|
||||||
ON
|
|
||||||
Employees.ManagerID = Manager.EmployeeID
|
|
||||||
WHERE
|
|
||||||
Employees.EmployeeID = '087652';
|
|
||||||
```
|
|
||||||
|
|
||||||
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
|
|
||||||
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
|
|
||||||
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
|
|
||||||
|
|
||||||
### Collapsible blocks
|
|
||||||
|
|
||||||
The [Details][6] extension which is also part of the [PyMdown Extensions][4]
|
|
||||||
package adds support for rendering collapsible Admonition blocks. This is
|
|
||||||
useful for FAQs or content that is of secondary nature.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
??? note "Phasellus posuere in sem ut cursus"
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
??? note "Phasellus posuere in sem ut cursus"
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
By adding a `+` sign directly after the start marker, blocks can be rendered
|
|
||||||
open by default.
|
|
||||||
|
|
||||||
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
|
|
||||||
|
|
||||||
## Types
|
|
||||||
|
|
||||||
Admonition supports user-defined type qualifiers which may influence the style
|
|
||||||
of the inserted block. Following is a list of type qualifiers provided by
|
|
||||||
Material for MkDocs, whereas the default type, and thus fallback for unknown
|
|
||||||
type qualifiers, is `note`.
|
|
||||||
|
|
||||||
### Note
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! note
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `note`
|
|
||||||
* `seealso`
|
|
||||||
|
|
||||||
### Abstract
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! abstract
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! abstract
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `abstract`
|
|
||||||
* `summary`
|
|
||||||
* `tldr`
|
|
||||||
|
|
||||||
### Info
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! info
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `info`
|
|
||||||
* `todo`
|
|
||||||
|
|
||||||
### Tip
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! tip
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `tip`
|
|
||||||
* `hint`
|
|
||||||
* `important`
|
|
||||||
|
|
||||||
### Success
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! success
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! success
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `success`
|
|
||||||
* `check`
|
|
||||||
* `done`
|
|
||||||
|
|
||||||
### Question
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! question
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! question
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `question`
|
|
||||||
* `help`
|
|
||||||
* `faq`
|
|
||||||
|
|
||||||
### Warning
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! warning
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `warning`
|
|
||||||
* `caution`
|
|
||||||
* `attention`
|
|
||||||
|
|
||||||
### Failure
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! failure
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! failure
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `failure`
|
|
||||||
* `fail`
|
|
||||||
* `missing`
|
|
||||||
|
|
||||||
### Danger
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! danger
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! danger
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `danger`
|
|
||||||
* `error`
|
|
||||||
|
|
||||||
### Bug
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! bug
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! bug
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `bug`
|
|
||||||
|
|
||||||
### Example
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! example
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `example`
|
|
||||||
|
|
||||||
### Quote
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
!!! quote
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
!!! quote
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
Qualifiers:
|
|
||||||
|
|
||||||
* `quote`
|
|
||||||
* `cite`
|
|
||||||
@ -1,89 +0,0 @@
|
|||||||
---
|
|
||||||
template: overrides/main.html
|
|
||||||
---
|
|
||||||
|
|
||||||
# Footnotes
|
|
||||||
|
|
||||||
[Footnotes][1] is another extension included in the standard Markdown library.
|
|
||||||
As the name says, it adds the ability to add inline footnotes to your
|
|
||||||
documentation.
|
|
||||||
|
|
||||||
[1]: https://python-markdown.github.io/extensions/footnotes/
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Add the following lines to `mkdocs.yml`:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
markdown_extensions:
|
|
||||||
- footnotes
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
The markup for footnotes is similar to the standard Markdown markup for links.
|
|
||||||
A reference is inserted in the text, which can then be defined at any point in
|
|
||||||
the document.
|
|
||||||
|
|
||||||
### Inserting the reference
|
|
||||||
|
|
||||||
The footnote reference is enclosed in square brackets and starts with a caret,
|
|
||||||
followed by an arbitrary label which may contain numeric identifiers [1, 2, 3,
|
|
||||||
...] or names [Granovetter et al. 1998]. The rendered references are always
|
|
||||||
consecutive superscripted numbers.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
|
|
||||||
|
|
||||||
### Inserting the content
|
|
||||||
|
|
||||||
The footnote content is also declared with a label, which must match the label
|
|
||||||
used for the footnote reference. It can be inserted at an arbitrary position in
|
|
||||||
the document and is always rendered at the bottom of the page. Furthermore, a
|
|
||||||
backlink is automatically added to the footnote reference.
|
|
||||||
|
|
||||||
#### on a single line
|
|
||||||
|
|
||||||
Short statements can be written on the same line.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
<a href="#fn:1">Jump to footnote at the bottom of the page</a>
|
|
||||||
|
|
||||||
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
||||||
|
|
||||||
#### on multiple lines
|
|
||||||
|
|
||||||
Paragraphs should be written on the next line. As with all Markdown blocks, the
|
|
||||||
content must be indented by four spaces.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
[^2]:
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
|
||||||
massa, nec semper lorem quam in massa.
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
[^2]:
|
|
||||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
|
||||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
|
|
||||||
auctor massa, nec semper lorem quam in massa.
|
|
||||||
|
|
||||||
<a href="#fn:2">Jump to footnote at the bottom of the page</a>
|
|
||||||
@ -1,135 +0,0 @@
|
|||||||
---
|
|
||||||
template: overrides/main.html
|
|
||||||
hero: Set heroes with metadata
|
|
||||||
path: tree/master/docs/extensions
|
|
||||||
source: metadata.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# Metadata
|
|
||||||
|
|
||||||
[Metadata][1] is an extension included in the standard Markdown library that
|
|
||||||
makes it possible to control certain properties in a page-specific context,
|
|
||||||
e.g. the page title or description.
|
|
||||||
|
|
||||||
[1]: https://python-markdown.github.io/extensions/meta_data/
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Add the following lines to `mkdocs.yml`:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
markdown_extensions:
|
|
||||||
- meta
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
Metadata is written as a series of key-value pairs at the beginning of the
|
|
||||||
Markdown document, delimited by a blank line which ends the metadata context.
|
|
||||||
Naturally, the metadata is stripped from the document before rendering the
|
|
||||||
actual page content and made available to the theme.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
---
|
|
||||||
title: Lorem ipsum dolor sit amet
|
|
||||||
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
|
|
||||||
path: path/to/file
|
|
||||||
source: file.js
|
|
||||||
---
|
|
||||||
|
|
||||||
# Headline
|
|
||||||
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
See the next section which covers the supported metadata.
|
|
||||||
|
|
||||||
### Setting a hero
|
|
||||||
|
|
||||||
Material for MkDocs exposes a simple text-only page-local hero via Metadata, as
|
|
||||||
you can see on the current page when you scroll to the top. It's as simple as:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
hero: Set heroes with metadata
|
|
||||||
```
|
|
||||||
|
|
||||||
### Linking sources
|
|
||||||
|
|
||||||
When a document is related to a specific source file and the `repo_url` is
|
|
||||||
defined inside the project's `mkdocs.yml`, the file can be linked using the
|
|
||||||
`source` key:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
source: file.js
|
|
||||||
```
|
|
||||||
|
|
||||||
The filename is appended to the `repo_url` set in `mkdocs.yml`, but can be
|
|
||||||
prefixed with a `path` to ensure correct path resolving. The name of the source
|
|
||||||
file is shown in the tooltip.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
path: tree/master/docs/extensions
|
|
||||||
source: metadata.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Redirecting to another page
|
|
||||||
|
|
||||||
It's sometimes necessary to move documents around in the navigation tree and
|
|
||||||
redirect users from the old URL to the new one. The `redirect` meta-tag allows
|
|
||||||
to create a redirection from the current document to the address specified in
|
|
||||||
the tag.
|
|
||||||
|
|
||||||
For instance, if your document contains:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
redirect: /new/url
|
|
||||||
```
|
|
||||||
|
|
||||||
accessing that document's URL will automatically redirect to `/new/url`.
|
|
||||||
|
|
||||||
### Overrides
|
|
||||||
|
|
||||||
#### Page title
|
|
||||||
|
|
||||||
The page title can be overridden on a per-document basis:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
title: Lorem ipsum dolor sit amet
|
|
||||||
```
|
|
||||||
|
|
||||||
This will set the `title` tag inside the document `head` for the current page
|
|
||||||
to the provided value. It will also override the default behavior of Material
|
|
||||||
for MkDocs which appends the site title using a dash as a separator to the page
|
|
||||||
title.
|
|
||||||
|
|
||||||
#### Page description
|
|
||||||
|
|
||||||
The page description can also be overridden on a per-document basis:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
|
|
||||||
```
|
|
||||||
|
|
||||||
This will set the `meta` tag containing the site description inside the
|
|
||||||
document `head` for the current page to the provided value.
|
|
||||||
|
|
||||||
#### Disqus
|
|
||||||
|
|
||||||
As described in the [getting started guide][3], Disqus can be enabled on a
|
|
||||||
per-document basis:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
disqus: your-shortname
|
|
||||||
```
|
|
||||||
|
|
||||||
Disqus can also be disabled for a specific page by setting it to an empty value:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
disqus: ''
|
|
||||||
```
|
|
||||||
|
|
||||||
[3]: ../getting-started.md#disqus
|
|
||||||
@ -1,375 +0,0 @@
|
|||||||
---
|
|
||||||
template: overrides/main.html
|
|
||||||
---
|
|
||||||
|
|
||||||
# PyMdown Extensions
|
|
||||||
|
|
||||||
[PyMdown Extensions][1] is a collection of Markdown extensions that add some
|
|
||||||
great missing features to the standard Markdown library. A compatible version
|
|
||||||
is always included with the theme.
|
|
||||||
|
|
||||||
[1]: https://facelessuser.github.io/pymdown-extensions/
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
The following list of extensions that are part of the PyMdown Extensions
|
|
||||||
package are recommended to be used together with Material for MkDocs:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
markdown_extensions:
|
|
||||||
- pymdownx.arithmatex
|
|
||||||
- pymdownx.betterem:
|
|
||||||
smart_enable: all
|
|
||||||
- pymdownx.caret
|
|
||||||
- pymdownx.critic
|
|
||||||
- pymdownx.details
|
|
||||||
- pymdownx.emoji:
|
|
||||||
emoji_index: !!python/name:materialx.emoji.twemoji
|
|
||||||
emoji_generator: !!python/name:materialx.emoji.to_svg
|
|
||||||
- pymdownx.inlinehilite
|
|
||||||
- pymdownx.magiclink
|
|
||||||
- pymdownx.mark
|
|
||||||
- pymdownx.smartsymbols
|
|
||||||
- pymdownx.superfences
|
|
||||||
- pymdownx.tasklist:
|
|
||||||
custom_checkbox: true
|
|
||||||
- pymdownx.tabbed
|
|
||||||
- pymdownx.tilde
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Arithmatex <small>MathJax</small>
|
|
||||||
|
|
||||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML"></script>
|
|
||||||
|
|
||||||
[Arithmatex][2] integrates Material for MkDocs with [MathJax][3] which parses
|
|
||||||
block-style and inline equations written in TeX markup and outputs them in
|
|
||||||
mathematical notation. See [this thread][4] for a short introduction and quick
|
|
||||||
reference on how to write equations in TeX syntax.
|
|
||||||
|
|
||||||
Besides activating the extension in the `mkdocs.yml`, the MathJax JavaScript
|
|
||||||
runtime needs to be included. This can be done with [additional JavaScript][5]:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
extra_javascript:
|
|
||||||
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
|
|
||||||
```
|
|
||||||
|
|
||||||
If you want to override the default MathJax configuration, you can do this by
|
|
||||||
adding another JavaScript file __before__ the MathJax runtime which contains
|
|
||||||
the MathJax configuration, e.g.:
|
|
||||||
|
|
||||||
``` js
|
|
||||||
window.MathJax = {
|
|
||||||
tex2jax: {
|
|
||||||
inlineMath: [ ["\\(","\\)"] ],
|
|
||||||
displayMath: [ ["\\[","\\]"] ]
|
|
||||||
},
|
|
||||||
TeX: {
|
|
||||||
TagSide: "right",
|
|
||||||
TagIndent: ".8em",
|
|
||||||
MultLineWidth: "85%",
|
|
||||||
equationNumbers: {
|
|
||||||
autoNumber: "AMS",
|
|
||||||
},
|
|
||||||
unicode: {
|
|
||||||
fonts: "STIXGeneral,'Arial Unicode MS'"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
displayAlign: "left",
|
|
||||||
showProcessingMessages: false,
|
|
||||||
messageStyle: "none"
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
Then, add the following lines to `mkdocs.yml`:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
extra_javascript:
|
|
||||||
- javascripts/extra.js
|
|
||||||
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
|
|
||||||
```
|
|
||||||
|
|
||||||
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
|
|
||||||
[3]: https://www.mathjax.org/
|
|
||||||
[4]: https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference
|
|
||||||
[5]: ../customization.md#additional-javascript
|
|
||||||
|
|
||||||
#### Blocks
|
|
||||||
|
|
||||||
Blocks are enclosed in `:::tex $$...$$` which are placed on separate lines.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` tex
|
|
||||||
$$
|
|
||||||
\frac{n!}{k!(n-k)!} = \binom{n}{k}
|
|
||||||
$$
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
$$
|
|
||||||
\frac{n!}{k!(n-k)!} = \binom{n}{k}
|
|
||||||
$$
|
|
||||||
|
|
||||||
#### Inline
|
|
||||||
|
|
||||||
Inline equations must be enclosed in `:::tex $...$`:
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` tex
|
|
||||||
Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
|
|
||||||
|
|
||||||
### BetterEm
|
|
||||||
|
|
||||||
[BetterEm][6] improves the handling of emphasis markup (__bold__ and _italic_)
|
|
||||||
within Markdown by providing a more sophisticated parser for better detecting
|
|
||||||
start and end tokens. Read the documentation for [usage notes][7].
|
|
||||||
|
|
||||||
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
|
|
||||||
[7]: https://facelessuser.github.io/pymdown-extensions/usage_notes/
|
|
||||||
|
|
||||||
### Caret
|
|
||||||
|
|
||||||
[Caret][8] makes it possible to highlight ^^inserted text^^. The portion of
|
|
||||||
text that should be marked as added must be enclosed in two carets `^^...^^`.
|
|
||||||
|
|
||||||
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
|
|
||||||
|
|
||||||
### Critic
|
|
||||||
|
|
||||||
[Critic][9] implements [Critic Markup][10], a Markdown extension that enables
|
|
||||||
the tracking of changes (additions, deletions and comments) on documents.
|
|
||||||
During compilation of the Markdown document, changes can be rendered (default),
|
|
||||||
accepted or rejected.
|
|
||||||
|
|
||||||
Text can be {--deleted--} and replacement text {++added++}. This can also be
|
|
||||||
combined into {~~one~>a single~~} operation. {==Highlighting==} is also
|
|
||||||
possible {>>and comments can be added inline<<}.
|
|
||||||
|
|
||||||
{==
|
|
||||||
|
|
||||||
Formatting can also be applied to blocks, by putting the opening and closing
|
|
||||||
tags on separate lines and adding new lines between the tags and the content.
|
|
||||||
|
|
||||||
==}
|
|
||||||
|
|
||||||
[9]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
|
|
||||||
[10]: http://criticmarkup.com/
|
|
||||||
|
|
||||||
### Details
|
|
||||||
|
|
||||||
[Details][11] adds [collapsible Admonition blocks][12] which can contain
|
|
||||||
arbitrary content using the HTML5 `details` and `summary` tags. Additionally,
|
|
||||||
all Admonition qualifiers can be used, e.g. `note`, `question`, `warning` etc.:
|
|
||||||
|
|
||||||
??? question "How many Prolog programmers does it take to change a lightbulb?"
|
|
||||||
|
|
||||||
Yes.
|
|
||||||
|
|
||||||
[11]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
|
|
||||||
[12]: ../admonition/#collapsible-blocks
|
|
||||||
|
|
||||||
### Emoji :tada:
|
|
||||||
|
|
||||||
[Emoji][13] adds the ability to insert, well, emojis! :smile:
|
|
||||||
|
|
||||||
By default, [Emoji][13] uses JoyPixles' emoji under the former name EmojiOne.
|
|
||||||
Recent versions of the extension lock support to an older version (2.2.7) due
|
|
||||||
to JoyPixels' newer, less permissible licenses included in later releases. This
|
|
||||||
restricts support to Unicode 9. To get the latest support for the current
|
|
||||||
Unicode version, you can use Twemoji instead which has a much more permissible
|
|
||||||
license. Simply override the default emoji index being used:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
markdown_extensions:
|
|
||||||
- pymdownx.emoji:
|
|
||||||
emoji_index: !!python/name:pymdownx.emoji.twemoji
|
|
||||||
emoji_generator: !!python/name:pymdownx.emoji.to_svg
|
|
||||||
```
|
|
||||||
|
|
||||||
To view all the available short names and emoji available, see
|
|
||||||
[Emoji's documentation][18] on your chosen index which includes links to the
|
|
||||||
files containing the short names and emoji associated with each supported
|
|
||||||
index.
|
|
||||||
|
|
||||||
!!! warning "Legal disclaimer"
|
|
||||||
|
|
||||||
Material has no affiliation with [JoyPixles][15] or [Twemoji][14], both
|
|
||||||
of which are licensed under [CC BY 4.0][16]. When including images or CSS
|
|
||||||
from either provider, please read their licenses to ensure proper
|
|
||||||
attribution: [EmojiOne][17] or [Twemoji][14].
|
|
||||||
|
|
||||||
### Icons :hatching_chick:
|
|
||||||
|
|
||||||
In addition, you can embed the Material Design icons, Fontawesome icons and
|
|
||||||
GitHub's Octicons directly from Markdown by using [Material for MkDocs's custom
|
|
||||||
emoji index][19]. It extends the Twemoji index with new short names that access
|
|
||||||
any of the included icons. To use the custom index, you need to use
|
|
||||||
`materialx.emoji` instead of `pymdownx.emoji`:
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
markdown_extensions:
|
|
||||||
- pymdownx.emoji:
|
|
||||||
emoji_index: !!python/name:materialx.emoji.twemoji
|
|
||||||
emoji_generator: !!python/name:materialx.emoji.to_svg
|
|
||||||
```
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
* :material-account-circle: – we can use Material Design icons
|
|
||||||
* :fontawesome-regular-laugh-wink: – we can also use FontAwesome icons
|
|
||||||
* :octicons-octoface-16: – that's not all, we can also use GitHub's Octicons
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
* :material-account-circle: – we can use [Material Design icons][20]
|
|
||||||
* :fontawesome-regular-laugh-wink: – we can also use [FontAwesome icons][21]
|
|
||||||
* :octicons-octoface-16: – that's not all, we can also use [GitHub's Octicons][22]
|
|
||||||
|
|
||||||
[13]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
|
|
||||||
[14]: https://twemoji.twitter.com/
|
|
||||||
[15]: https://www.joypixels.com/
|
|
||||||
[16]: https://creativecommons.org/licenses/by/4.0/legalcode
|
|
||||||
[17]: https://github.com/joypixels/emojione#emojione-version-2
|
|
||||||
[18]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
|
|
||||||
[19]: https://github.com/facelessuser/mkdocs-material-extensions
|
|
||||||
[20]: https://material.io/resources/icons/
|
|
||||||
[21]: https://fontawesome.com/icons?d=gallery&m=free
|
|
||||||
[22]: https://octicons.github.com/
|
|
||||||
|
|
||||||
### InlineHilite
|
|
||||||
|
|
||||||
[InlineHilite][23] adds support for inline code highlighting. It's useful for
|
|
||||||
short snippets included within body copy, e.g. `#!js var test = 0;` and can be
|
|
||||||
activated by prefixing inline code with a shebang and language identifier,
|
|
||||||
e.g. `#!js`.
|
|
||||||
|
|
||||||
[23]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
|
||||||
|
|
||||||
### MagicLink
|
|
||||||
|
|
||||||
[MagicLink][24] detects links in Markdown and auto-generates the necessary
|
|
||||||
markup, so no special syntax is required. It auto-links `http[s]://` and
|
|
||||||
`ftp://` links, as well as references to email addresses.
|
|
||||||
|
|
||||||
[24]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
|
|
||||||
|
|
||||||
### Mark
|
|
||||||
|
|
||||||
[Mark][25] adds the ability to ==highlight text== like it was marked with a
|
|
||||||
==text marker==. The portion of text that should be highlighted must be
|
|
||||||
enclosed in two equal signs `==...==`.
|
|
||||||
|
|
||||||
[25]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
|
|
||||||
|
|
||||||
### SmartSymbols
|
|
||||||
|
|
||||||
[SmartSymbols][26] converts markup for special characters into their
|
|
||||||
corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
|
|
||||||
symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
|
|
||||||
|
|
||||||
[26]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
|
|
||||||
|
|
||||||
### SuperFences
|
|
||||||
|
|
||||||
[SuperFences][27] provides the ability to nest code blocks under blockquotes,
|
|
||||||
lists and other block elements, which the [Fenced Code Blocks][28] extension
|
|
||||||
from the standard Markdown library doesn't parse correctly.
|
|
||||||
|
|
||||||
SuperFences does also allow [grouping code blocks with tabs][29].
|
|
||||||
|
|
||||||
[27]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
|
||||||
[28]: https://python-markdown.github.io/extensions/fenced_code_blocks/
|
|
||||||
[29]: codehilite.md#grouping-code-blocks
|
|
||||||
|
|
||||||
### Tabbed
|
|
||||||
|
|
||||||
[Tabbed][30] adds support for creating tabbed groups of Markdown content.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
=== "Fruit List"
|
|
||||||
- :apple: Apple
|
|
||||||
- :banana: Banana
|
|
||||||
- :kiwi: Kiwi
|
|
||||||
|
|
||||||
=== "Fruit Table"
|
|
||||||
Fruit | Color
|
|
||||||
--------------- | -----
|
|
||||||
:apple: Apple | Red
|
|
||||||
:banana: Banana | Yellow
|
|
||||||
:kiwi: Kiwi | Green
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
=== "Fruit List"
|
|
||||||
- :apple: Apple
|
|
||||||
- :banana: Banana
|
|
||||||
- :kiwi: Kiwi
|
|
||||||
|
|
||||||
=== "Fruit Table"
|
|
||||||
Fruit | Color
|
|
||||||
--------------- | -----
|
|
||||||
:apple: Apple | Red
|
|
||||||
:banana: Banana | Yellow
|
|
||||||
:kiwi: Kiwi | Green
|
|
||||||
|
|
||||||
[30]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
|
|
||||||
|
|
||||||
### Tasklist
|
|
||||||
|
|
||||||
[Tasklist][31] adds support for styled checkbox lists. This is useful for
|
|
||||||
keeping track of tasks and showing what has been done and has yet to be done.
|
|
||||||
Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or
|
|
||||||
`[x]` for filled checkboxes.
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
``` markdown
|
|
||||||
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
|
|
||||||
* [x] Nulla lobortis egestas semper
|
|
||||||
* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
|
|
||||||
* [ ] Vestibulum convallis sit amet nisi a tincidunt
|
|
||||||
* [x] In hac habitasse platea dictumst
|
|
||||||
* [x] In scelerisque nibh non dolor mollis congue sed et metus
|
|
||||||
* [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
|
|
||||||
* [ ] Praesent sed risus massa
|
|
||||||
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
|
||||||
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
|
|
||||||
```
|
|
||||||
|
|
||||||
Result:
|
|
||||||
|
|
||||||
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
|
|
||||||
* [x] Nulla lobortis egestas semper
|
|
||||||
* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
|
|
||||||
* [ ] Vestibulum convallis sit amet nisi a tincidunt
|
|
||||||
* [x] In hac habitasse platea dictumst
|
|
||||||
* [x] In scelerisque nibh non dolor mollis congue sed et metus
|
|
||||||
* [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
|
|
||||||
* [ ] Praesent sed risus massa
|
|
||||||
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
|
||||||
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
|
|
||||||
|
|
||||||
[31]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
|
|
||||||
|
|
||||||
### Tilde
|
|
||||||
|
|
||||||
[Tilde][32] provides an easy way to ~~strike through~~ cross out text.
|
|
||||||
The portion of text that should be erased must be enclosed in two tildes
|
|
||||||
`~~...~~` and the extension will take care of the rest.
|
|
||||||
|
|
||||||
[32]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
|
|
||||||
@ -16,7 +16,7 @@ fit your brand identity by using [CSS variables][2].
|
|||||||
|
|
||||||
### Color scheme
|
### Color scheme
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][3] · :octicons-tools-24: Default: `default`
|
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default`
|
||||||
|
|
||||||
Material for MkDocs supports two _color schemes_: a light mode, which is just
|
Material for MkDocs supports two _color schemes_: a light mode, which is just
|
||||||
called `default`, and a dark mode, which is called `slate`. The color scheme
|
called `default`, and a dark mode, which is called `slate`. The color scheme
|
||||||
@ -62,7 +62,7 @@ theme:
|
|||||||
|
|
||||||
### Primary color
|
### Primary color
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][4] · :octicons-tools-24: Default: `indigo`
|
[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo`
|
||||||
|
|
||||||
The _primary color_ is used for the header, the sidebar, text links and several
|
The _primary color_ is used for the header, the sidebar, text links and several
|
||||||
other components. In order to change the primary color, set the following value
|
other components. In order to change the primary color, set the following value
|
||||||
@ -117,7 +117,7 @@ color:
|
|||||||
|
|
||||||
### Accent color
|
### Accent color
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: `indigo`
|
[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo`
|
||||||
|
|
||||||
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
|
||||||
@ -184,9 +184,12 @@ color:
|
|||||||
|
|
||||||
## Customization
|
## Customization
|
||||||
|
|
||||||
Material for MkDocs implements colors using [CSS variables][6] (custom
|
[:octicons-file-code-24: Source][6] ·
|
||||||
|
:octicons-mortar-board-24: Difficulty: easy
|
||||||
|
|
||||||
|
Material for MkDocs implements colors using [CSS variables][7] (custom
|
||||||
properties). If you want to customize the colors beyond the palette (e.g. to
|
properties). If you want to customize the colors beyond the palette (e.g. to
|
||||||
use your brand-specific colors), you can add an [additional stylesheet][7] and
|
use your brand-specific colors), you can add an [additional stylesheet][8] and
|
||||||
tweak the following CSS variables:
|
tweak the following CSS variables:
|
||||||
|
|
||||||
``` css
|
``` css
|
||||||
@ -217,7 +220,7 @@ tweak the following CSS variables:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
The colors of [code blocks][8], [admonitions][9], text links and the footer can
|
The colors of [code blocks][9], [admonitions][10], text links and the footer can
|
||||||
be adjusted through dedicated CSS variables, which partly default to the base
|
be adjusted through dedicated CSS variables, which partly default to the base
|
||||||
colors or neutral colors:
|
colors or neutral colors:
|
||||||
|
|
||||||
@ -245,7 +248,8 @@ colors or neutral colors:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
|
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss
|
||||||
[7]: ../customization.md#additional-stylesheets
|
[7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
|
||||||
[8]: ../extensions/codehilite.md
|
[8]: ../customization.md#additional-stylesheets
|
||||||
[9]: ../extensions/admonition.md
|
[9]: ../writing/code-blocks.md
|
||||||
|
[10]: ../writing/admonitions.md
|
||||||
|
|||||||
@ -15,7 +15,8 @@ should be used.
|
|||||||
|
|
||||||
### Regular font
|
### Regular font
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: [`Roboto`][3]
|
[:octicons-file-code-24: Source][2] ·
|
||||||
|
:octicons-milestone-24: Default: [`Roboto`][3]
|
||||||
|
|
||||||
The _regular font_ is used for all body copy, headlines, and essentially
|
The _regular font_ is used for all body copy, headlines, and essentially
|
||||||
everything that does not need to be proportionally spaced. It can be set to any
|
everything that does not need to be proportionally spaced. It can be set to any
|
||||||
@ -34,8 +35,8 @@ The typeface will be loaded in 300, 400, _400i_ and __700__.
|
|||||||
|
|
||||||
### Proportional font
|
### Proportional font
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default:
|
[:octicons-file-code-24: Source][2] ·
|
||||||
[`Roboto Mono`][4]
|
:octicons-milestone-24: Default: [`Roboto Mono`][4]
|
||||||
|
|
||||||
The _proportional font_ is used for code blocks and can be configured separately.
|
The _proportional font_ is used for code blocks and can be configured separately.
|
||||||
Just like the regular font, it can be set to any valid [Google Font][1] from
|
Just like the regular font, it can be set to any valid [Google Font][1] from
|
||||||
@ -53,6 +54,9 @@ The typeface will be loaded in 400.
|
|||||||
|
|
||||||
## Customization
|
## Customization
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][2] ·
|
||||||
|
:octicons-mortar-board-24: Difficulty: easy
|
||||||
|
|
||||||
If you want to load fonts from other destinations or don't want to use Google
|
If you want to load fonts from other destinations or don't want to use Google
|
||||||
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, add the following lines
|
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, add the following lines
|
||||||
to `mkdocs.yml`:
|
to `mkdocs.yml`:
|
||||||
|
|||||||
@ -12,7 +12,7 @@ search can be configured to use a language-specific stemmer (if available).
|
|||||||
|
|
||||||
### Site language
|
### Site language
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][1] · :octicons-tools-24: Default: `en`
|
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
|
||||||
|
|
||||||
You can set the language from `mkdocs.yml` with:
|
You can set the language from `mkdocs.yml` with:
|
||||||
|
|
||||||
@ -23,18 +23,6 @@ theme:
|
|||||||
|
|
||||||
The following languages are supported:
|
The following languages 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="tx-columns">
|
<ul class="tx-columns">
|
||||||
<li><code>af</code> / Afrikaans</li>
|
<li><code>af</code> / Afrikaans</li>
|
||||||
<li><code>ar</code> / Arabic</li>
|
<li><code>ar</code> / Arabic</li>
|
||||||
@ -90,22 +78,22 @@ The following languages are supported:
|
|||||||
|
|
||||||
### Site search language
|
### Site search language
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: automatically
|
[:octicons-file-code-24: Source][2] ·
|
||||||
set
|
:octicons-milestone-24: Default: _automatically set_
|
||||||
|
|
||||||
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
|
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
|
||||||
work properly. Material for MkDocs relies on [lunr-languages][3] to provide this
|
work properly. Material for MkDocs relies on [lunr-languages][3] to provide this
|
||||||
functionality. See the [search plugin documentation][4] for more information.
|
functionality. See the [setting up site search][4] guide for more information.
|
||||||
|
|
||||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
|
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
|
||||||
[3]: https://github.com/MihaiValentin/lunr-languages
|
[3]: https://github.com/MihaiValentin/lunr-languages
|
||||||
[4]: ../plugins/search.md#language
|
[4]: setting-up-site-search.md
|
||||||
|
|
||||||
|
|
||||||
### Directionality
|
### Directionality
|
||||||
|
|
||||||
[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: automatically
|
[:octicons-file-code-24: Source][5] ·
|
||||||
set
|
:octicons-milestone-24: Default: _automatically set_
|
||||||
|
|
||||||
While many languages are read `ltr` (left-to-right), Material for MkDocs also
|
While many languages are read `ltr` (left-to-right), Material for MkDocs also
|
||||||
supports `rtl` (right-to-left) directionality which is inferred from the
|
supports `rtl` (right-to-left) directionality which is inferred from the
|
||||||
@ -140,6 +128,9 @@ directionality:
|
|||||||
|
|
||||||
## Customization
|
## Customization
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][1] ·
|
||||||
|
:octicons-mortar-board-24: Difficulty: easy
|
||||||
|
|
||||||
If you want to customize some (or all) of the translations for your language,
|
If you want to customize some (or all) of the translations for your language,
|
||||||
you may follow the guide on [theme extension][6] and create a new partial in
|
you may follow the guide on [theme extension][6] and create a new partial in
|
||||||
`partials/language`, e.g. `en-custom.html`. Next, look up the translation you
|
`partials/language`, e.g. `en-custom.html`. Next, look up the translation you
|
||||||
|
|||||||
@ -2,7 +2,7 @@
|
|||||||
template: overrides/main.html
|
template: overrides/main.html
|
||||||
---
|
---
|
||||||
|
|
||||||
# Navigation
|
# Setting up navigation
|
||||||
|
|
||||||
A clear and concise navigation structure is an important aspect of good project
|
A clear and concise navigation structure is an important aspect of good project
|
||||||
documentation. Material for MkDocs provides several options to configure the
|
documentation. Material for MkDocs provides several options to configure the
|
||||||
@ -103,10 +103,10 @@ customize its appearance:
|
|||||||
|
|
||||||
`permalink`
|
`permalink`
|
||||||
|
|
||||||
: This option adds an anchor link containing the paragraph symbol `¶` or
|
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
|
||||||
another custom symbol at the end of each headline, exactly like on the page
|
containing the paragraph symbol `¶` or another custom symbol at the end of
|
||||||
you're currently viewing, which Material for MkDocs will make appear on
|
each headline, exactly like on the page you're currently viewing, which
|
||||||
hover:
|
Material for MkDocs will make appear on hover:
|
||||||
|
|
||||||
=== "¶"
|
=== "¶"
|
||||||
|
|
||||||
@ -126,10 +126,10 @@ customize its appearance:
|
|||||||
|
|
||||||
`slugify`
|
`slugify`
|
||||||
|
|
||||||
: This option allows for customization of the slug function. For some
|
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
|
||||||
languages, the standard slug function may not produce good and readable
|
customization of the slug function. For some languages, the default may not
|
||||||
identifiers. Consider using another slug function like for example those
|
produce good and readable identifiers. Consider using another slug function
|
||||||
from [Python Markdown Extensions][8]:
|
like for example those from [Python Markdown Extensions][8]:
|
||||||
|
|
||||||
=== "Unicode"
|
=== "Unicode"
|
||||||
|
|
||||||
@ -149,10 +149,10 @@ customize its appearance:
|
|||||||
|
|
||||||
`toc_depth`
|
`toc_depth`
|
||||||
|
|
||||||
: Define the range of levels to be included in the table of contents. This is
|
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
|
||||||
especially useful for project documentation with deeply structured headings
|
included in the table of contents. This may be useful for project
|
||||||
to decrease the length of the table of contents, or to remove the table of
|
documentation with deeply structured headings to decrease the length of the
|
||||||
contents altogether:
|
table of contents, or to remove the table of contents altogether:
|
||||||
|
|
||||||
=== "Hide levels 4-6"
|
=== "Hide levels 4-6"
|
||||||
|
|
||||||
@ -181,10 +181,14 @@ them at your own risk._
|
|||||||
|
|
||||||
## Customization
|
## Customization
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][9] ·
|
||||||
|
:octicons-mortar-board-24: Difficulty: moderate
|
||||||
|
|
||||||
All navigational elements are defined as partials and can be overridden through
|
All navigational elements are defined as partials and can be overridden through
|
||||||
[theme extension][9] by [overriding partials][10] or [blocks][11], i.e.
|
[theme extension][10] by [overriding partials][11] or [blocks][12], i.e.
|
||||||
`site_nav` which contains both sidebars, `tabs` and `footer`.
|
`site_nav` which contains both sidebars, `tabs` and `footer`.
|
||||||
|
|
||||||
[9]: ../customization.md#extending-the-theme
|
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials
|
||||||
[10]: ../customization.md#overriding-partials
|
[10]: ../customization.md#extending-the-theme
|
||||||
[11]: ../customization.md#overriding-blocks
|
[11]: ../customization.md#overriding-partials
|
||||||
|
[12]: ../customization.md#overriding-blocks
|
||||||
271
docs/guides/setting-up-site-search.md
Normal file
271
docs/guides/setting-up-site-search.md
Normal file
@ -0,0 +1,271 @@
|
|||||||
|
---
|
||||||
|
template: overrides/main.html
|
||||||
|
---
|
||||||
|
|
||||||
|
# Setting up site search
|
||||||
|
|
||||||
|
Material for MkDocs provides a great, client-side search implementation,
|
||||||
|
omitting the need for the integation of third-party services, which might
|
||||||
|
violate data privacy regulations. Furthermore, with some effort, search can
|
||||||
|
be made available [offline][1].
|
||||||
|
|
||||||
|
[1]: #offline-search
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Built-in search
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][2] ·
|
||||||
|
[:octicons-cpu-24: Plugin][3]
|
||||||
|
|
||||||
|
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
|
||||||
|
are used:
|
||||||
|
|
||||||
|
``` yaml
|
||||||
|
plugins:
|
||||||
|
- search
|
||||||
|
```
|
||||||
|
|
||||||
|
The following options are supported:
|
||||||
|
|
||||||
|
`lang`
|
||||||
|
|
||||||
|
: :octicons-milestone-24: Default: _automatically set_ · This option allows
|
||||||
|
to include the language-specific stemmers provided by [lunr-languages][5].
|
||||||
|
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
|
||||||
|
languages:
|
||||||
|
|
||||||
|
=== "A single language"
|
||||||
|
|
||||||
|
``` yaml
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
lang: ru
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Multiple languages"
|
||||||
|
|
||||||
|
``` yaml
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
lang:
|
||||||
|
- en
|
||||||
|
- ru
|
||||||
|
```
|
||||||
|
|
||||||
|
The following languages are supported:
|
||||||
|
|
||||||
|
<ul class="tx-columns">
|
||||||
|
<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>
|
||||||
|
|
||||||
|
_Material for MkDocs also tries to support languages which are not part of
|
||||||
|
this list, by automatically chosing the best-matching stemmer_.
|
||||||
|
|
||||||
|
!!! 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.
|
||||||
|
|
||||||
|
`separator`
|
||||||
|
|
||||||
|
: :octicons-milestone-24: Default: _automatically set_ – The separator for
|
||||||
|
indexing and query tokenization can be customized, which makes it possible
|
||||||
|
to index parts of words that are separated by other characters than
|
||||||
|
whitespace and `-`, e.g. by including `.`:
|
||||||
|
|
||||||
|
``` yaml
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
separator: '[\s\-\.]+'
|
||||||
|
```
|
||||||
|
|
||||||
|
`prebuild_index`
|
||||||
|
|
||||||
|
: :octicons-milestone-24: Default: `false` · :octicons-beaker-24:
|
||||||
|
Experimental – MkDocs can generate a [prebuilt index][7] 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:
|
||||||
|
|
||||||
|
``` yaml
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
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.
|
||||||
|
|
||||||
|
_Material for MkDocs doesn't provide official support for the other options of
|
||||||
|
this plugin, so they may be supported but can also yield weird results. Use
|
||||||
|
them at your own risk._
|
||||||
|
|
||||||
|
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
|
||||||
|
[3]: https://www.mkdocs.org/user-guide/configuration/#search
|
||||||
|
[4]: https://lunrjs.com
|
||||||
|
[5]: https://github.com/MihaiValentin/lunr-languages
|
||||||
|
[6]: changing-the-language.md#site-language
|
||||||
|
[7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
|
||||||
|
|
||||||
|
### Offline search
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][8] ·
|
||||||
|
[:octicons-cpu-24: Plugin][9] · :octicons-beaker-24: Experimental
|
||||||
|
|
||||||
|
If you distribute your documentation as `*.html` files, the built-in search
|
||||||
|
will not work out-of-the-box due to the restrictions modern browsers impose for
|
||||||
|
security reasons. This can be mitigated with the [localsearch plugin][9] in
|
||||||
|
combination with @squidfunk's [iframe-worker][10] polyfill.
|
||||||
|
|
||||||
|
For [setup instructions][11], refer to the official documentation.
|
||||||
|
|
||||||
|
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
|
||||||
|
[9]: https://github.com/wilhelmer/mkdocs-localsearch/
|
||||||
|
[10]: https://github.com/squidfunk/iframe-worker
|
||||||
|
[11]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
|
||||||
|
|
||||||
|
## 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_.
|
||||||
|
This is where it deviates from other themes.
|
||||||
|
|
||||||
|
This section explains how search can be customized to tailor it to your needs.
|
||||||
|
|
||||||
|
### Query transformation
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][12] ·
|
||||||
|
: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][13]:
|
||||||
|
|
||||||
|
``` 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.
|
||||||
|
*
|
||||||
|
* 4. Append a wildcard to the end of every word to make every word a prefix
|
||||||
|
* query in order to provide a good typeahead experience, by adding an
|
||||||
|
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
|
||||||
|
* any non-control character, or a word boundary.
|
||||||
|
*
|
||||||
|
* @param value - Query value
|
||||||
|
*
|
||||||
|
* @return Transformed query value
|
||||||
|
*/
|
||||||
|
function defaultTransform(value: string): string {
|
||||||
|
return value
|
||||||
|
.split(/"([^"]+)"/g) /* => 1 */
|
||||||
|
.map((terms, i) => i & 1
|
||||||
|
? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +")
|
||||||
|
: terms
|
||||||
|
)
|
||||||
|
.join("")
|
||||||
|
.replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* => 2 */
|
||||||
|
.trim() /* => 3 */
|
||||||
|
.replace(/\s+|(?![^\x00-\x7F]|^)$|\b$/g, "* ") /* => 4 */
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If you want to switch to the default behavior of the `mkdocs` or `readthedocs`
|
||||||
|
template, both of which don't transform the query prior to submission, or
|
||||||
|
customize the `transform` function, you can do this by [overriding the
|
||||||
|
`config` block][14]:
|
||||||
|
|
||||||
|
``` jinja
|
||||||
|
{% block config %}
|
||||||
|
<script>
|
||||||
|
var search = {
|
||||||
|
transform: function(query) {
|
||||||
|
return query
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
{% endblock %}
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
|
||||||
|
[13]: ../customization.md#extending-the-theme
|
||||||
|
[14]: ../customization.md#overriding-blocks
|
||||||
|
|
||||||
|
### Worker implementation
|
||||||
|
|
||||||
|
[:octicons-file-code-24: Source][15] ·
|
||||||
|
:octicons-mortar-board-24: Difficulty: challenging
|
||||||
|
|
||||||
|
Material for MkDocs implements search as part of a [web worker][16]. 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][14]:
|
||||||
|
|
||||||
|
``` jinja
|
||||||
|
{% block config %}
|
||||||
|
<script>
|
||||||
|
var search = {
|
||||||
|
worker: "<url>"
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
{% endblock %}
|
||||||
|
```
|
||||||
|
|
||||||
|
Communication with the search worker is implemented using a standardized
|
||||||
|
message format using _discriminated unions_, i.e. through the `type` property
|
||||||
|
of the message. See the following interface definitions to learn about the
|
||||||
|
message formats:
|
||||||
|
|
||||||
|
- [:octicons-file-code-24: `SearchMessage`][17]
|
||||||
|
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]
|
||||||
|
|
||||||
|
The sequence and direction of messages is rather intuitive:
|
||||||
|
|
||||||
|
- :octicons-arrow-right-24: `SearchSetupMessage`
|
||||||
|
- :octicons-arrow-left-24: `SearchReadyMessage`
|
||||||
|
- :octicons-arrow-right-24: `SearchQueryMessage`
|
||||||
|
- :octicons-arrow-left-24: `SearchResultMessage`
|
||||||
|
|
||||||
|
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
|
||||||
|
[16]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
|
||||||
|
[17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
|
||||||
|
[18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts
|
||||||
@ -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.
|
|
||||||
@ -30,7 +30,7 @@ pip show mkdocs-material
|
|||||||
|
|
||||||
### 5.3.2 <small>_ June 21, 2020</small>
|
### 5.3.2 <small>_ June 21, 2020</small>
|
||||||
|
|
||||||
* Improved search type-ahead experience with non-Latin characters
|
* Improved search typeahead experience with non-Latin characters
|
||||||
* Fixed #1753: Japanese search doesn't work anymore
|
* Fixed #1753: Japanese search doesn't work anymore
|
||||||
|
|
||||||
### 5.3.1 <small>_ June 20, 2020</small>
|
### 5.3.1 <small>_ June 20, 2020</small>
|
||||||
|
|||||||
@ -2,7 +2,7 @@
|
|||||||
template: overrides/main.html
|
template: overrides/main.html
|
||||||
---
|
---
|
||||||
|
|
||||||
# Syntax highlighting
|
# Code blocks
|
||||||
|
|
||||||
Code blocks and examples are an essential part of technical project
|
Code blocks and examples are an essential part of technical project
|
||||||
documentation. Material for MkDocs provides different ways to set up syntax
|
documentation. Material for MkDocs provides different ways to set up syntax
|
||||||
@ -23,11 +23,11 @@ configuring syntax highlighting of code blocks:
|
|||||||
|
|
||||||
`use_pygments`
|
`use_pygments`
|
||||||
|
|
||||||
: This option allows to control whether highlighting should be carried out
|
: :octicons-milestone-24: Default: `true` · This option allows to control
|
||||||
during build time by [Pygments][1] (default, recommended) or runtime with
|
whether highlighting should be carried out during build time by
|
||||||
a JavaScript highlighter. Remember to add the necessary
|
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
|
||||||
[additional stylesheets][5] and [JavaScript][6] if you want to use the
|
necessary [additional stylesheets][5] and [JavaScript][6] if you want to
|
||||||
latter:
|
use the latter:
|
||||||
|
|
||||||
=== "Pygments"
|
=== "Pygments"
|
||||||
|
|
||||||
@ -72,10 +72,10 @@ configuring syntax highlighting of code blocks:
|
|||||||
|
|
||||||
`linenums`
|
`linenums`
|
||||||
|
|
||||||
: This option will add line numbers to _all_ code blocks. If you wish to add
|
: :octicons-milestone-24: Default: `false` · This option will add line numbers
|
||||||
line numbers to _some_, but not all code blocks, consult the section on
|
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
|
||||||
[adding line numbers][9] later in this document, which also contains some
|
code blocks, consult the section on [adding line numbers][9] later in this
|
||||||
tips on working with line numbers:
|
document, which also contains some tips on working with line numbers:
|
||||||
|
|
||||||
``` yaml
|
``` yaml
|
||||||
markdown_extensions:
|
markdown_extensions:
|
||||||
@ -85,10 +85,10 @@ configuring syntax highlighting of code blocks:
|
|||||||
|
|
||||||
`linenums_style`
|
`linenums_style`
|
||||||
|
|
||||||
: The Highlight extension provides three ways to add line numbers, all of
|
: :octicons-milestone-24: Default: `table` · The Highlight extension provides
|
||||||
which are supported by Material for MkDocs. While `table` (default,
|
three ways to add line numbers, all of which are supported by Material for
|
||||||
recommended) wraps a code block in a table, `inline` and `pymdownx.inline`
|
MkDocs. While `table` wraps a code block in a table, `inline` and
|
||||||
render line numbers as part of the line itself:
|
`pymdownx.inline` render line numbers as part of the line itself:
|
||||||
|
|
||||||
``` yaml
|
``` yaml
|
||||||
markdown_extensions:
|
markdown_extensions:
|
||||||
@ -133,14 +133,6 @@ See the section on [inline code blocks][11] for usage information.
|
|||||||
[10]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
[10]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
||||||
[11]: #inline-code-blocks
|
[11]: #inline-code-blocks
|
||||||
|
|
||||||
## Customization
|
|
||||||
|
|
||||||
While syntax highlighting is implemented with [Pygments][1] or JavaScript,
|
|
||||||
Material for MkDocs defines the [appeareance][12] of code blocks, which can be
|
|
||||||
adjusted with [additional stylesheets][5].
|
|
||||||
|
|
||||||
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_codehilite.scss
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
This section discusses how to use different syntax highlighting features with
|
This section discusses how to use different syntax highlighting features with
|
||||||
@ -151,7 +143,7 @@ a JavaScript syntaxhighlighter.
|
|||||||
|
|
||||||
Code blocks must be enclosed with two separate lines containing three backticks.
|
Code blocks must be enclosed with two separate lines containing three backticks.
|
||||||
To add code highlighting to those blocks, add the language short name directly
|
To add code highlighting to those blocks, add the language short name directly
|
||||||
after the opening block. See the [list of available lexers][13] to find the
|
after the opening block. See the [list of available lexers][12] to find the
|
||||||
short name for a given language.
|
short name for a given language.
|
||||||
|
|
||||||
_Example_:
|
_Example_:
|
||||||
@ -168,7 +160,7 @@ _Result_:
|
|||||||
import tensorflow as tf
|
import tensorflow as tf
|
||||||
```
|
```
|
||||||
|
|
||||||
[13]: https://pygments.org/docs/lexers/
|
[12]: https://pygments.org/docs/lexers/
|
||||||
|
|
||||||
### Adding line numbers
|
### Adding line numbers
|
||||||
|
|
||||||
@ -233,7 +225,7 @@ def bubble_sort(items):
|
|||||||
|
|
||||||
### Inline code blocks
|
### Inline code blocks
|
||||||
|
|
||||||
When [InlineHilite][14] is enabled, inline code blocks can be highlighted by
|
When [InlineHilite][13] is enabled, inline code blocks can be highlighted by
|
||||||
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
|
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
|
||||||
the language short name.
|
the language short name.
|
||||||
|
|
||||||
@ -247,4 +239,4 @@ _Result_:
|
|||||||
|
|
||||||
The `#!python range()` function is used to generate a sequence of numbers.
|
The `#!python range()` function is used to generate a sequence of numbers.
|
||||||
|
|
||||||
[14]: #inlinehilite
|
[13]: #inlinehilite
|
||||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"assets/javascripts/bundle.js": "assets/javascripts/bundle.b49b2592.min.js",
|
"assets/javascripts/bundle.js": "assets/javascripts/bundle.1b3af799.min.js",
|
||||||
"assets/javascripts/bundle.js.map": "assets/javascripts/bundle.b49b2592.min.js.map",
|
"assets/javascripts/bundle.js.map": "assets/javascripts/bundle.1b3af799.min.js.map",
|
||||||
"assets/javascripts/vendor.js": "assets/javascripts/vendor.877163d5.min.js",
|
"assets/javascripts/vendor.js": "assets/javascripts/vendor.877163d5.min.js",
|
||||||
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
|
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
|
||||||
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
|
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
|
||||||
|
|||||||
@ -183,7 +183,7 @@
|
|||||||
</div>
|
</div>
|
||||||
{% block scripts %}
|
{% block scripts %}
|
||||||
<script src="{{ 'assets/javascripts/vendor.877163d5.min.js' | url }}"></script>
|
<script src="{{ 'assets/javascripts/vendor.877163d5.min.js' | url }}"></script>
|
||||||
<script src="{{ 'assets/javascripts/bundle.b49b2592.min.js' | url }}"></script>
|
<script src="{{ 'assets/javascripts/bundle.1b3af799.min.js' | url }}"></script>
|
||||||
{%- set translations = {} -%}
|
{%- set translations = {} -%}
|
||||||
{%- for key in [
|
{%- for key in [
|
||||||
"clipboard.copy",
|
"clipboard.copy",
|
||||||
|
|||||||
16
mkdocs.yml
16
mkdocs.yml
@ -131,12 +131,14 @@ nav:
|
|||||||
- Customization: customization.md
|
- Customization: customization.md
|
||||||
- Troubleshooting: troubleshooting.md
|
- Troubleshooting: troubleshooting.md
|
||||||
- Data privacy: data-privacy.md
|
- Data privacy: data-privacy.md
|
||||||
|
- Writing:
|
||||||
|
- Code blocks: writing/code-blocks.md
|
||||||
- Guides:
|
- Guides:
|
||||||
- Changing colors: guides/changing-colors.md
|
- Changing colors: guides/changing-colors.md
|
||||||
- Changing the fonts: guides/changing-the-fonts.md
|
- Changing the fonts: guides/changing-the-fonts.md
|
||||||
- Changing the language: guides/changing-the-language.md
|
- Changing the language: guides/changing-the-language.md
|
||||||
- Navigation: guides/navigation.md
|
- Setting up navigation: guides/setting-up-navigation.md
|
||||||
- Syntax highlighting: guides/syntax-highlighting.md
|
- Setting up site search: guides/setting-up-site-search.md
|
||||||
- Adding a git repository: guides/adding-a-git-repository.md
|
- Adding a git repository: guides/adding-a-git-repository.md
|
||||||
- Adding icons and emojis: guides/adding-icons-and-emojis.md
|
- Adding icons and emojis: guides/adding-icons-and-emojis.md
|
||||||
- Adding footer links: guides/adding-footer-links.md
|
- Adding footer links: guides/adding-footer-links.md
|
||||||
@ -144,16 +146,6 @@ nav:
|
|||||||
- Adding a comment system: guides/adding-a-comment-system.md
|
- Adding a comment system: guides/adding-a-comment-system.md
|
||||||
- Adding an announcement bar: guides/adding-an-announcement-bar.md
|
- Adding an announcement bar: guides/adding-an-announcement-bar.md
|
||||||
- Adding a landing page: guides/adding-a-landing-page.md
|
- Adding a landing page: guides/adding-a-landing-page.md
|
||||||
- Extensions:
|
|
||||||
- Admonition: extensions/admonition.md
|
|
||||||
- Footnotes: extensions/footnotes.md
|
|
||||||
- Metadata: extensions/metadata.md
|
|
||||||
- PyMdown: extensions/pymdown.md
|
|
||||||
- Plugins:
|
|
||||||
- Search: plugins/search.md
|
|
||||||
- Minification: plugins/minification.md
|
|
||||||
- Revision date: plugins/revision-date.md
|
|
||||||
- Awesome pages: plugins/awesome-pages.md
|
|
||||||
- Releases:
|
- Releases:
|
||||||
- Upgrading to 5.x: releases/5.md
|
- Upgrading to 5.x: releases/5.md
|
||||||
- Upgrading to 4.x: releases/4.md
|
- Upgrading to 4.x: releases/4.md
|
||||||
|
|||||||
@ -55,7 +55,7 @@ export type SearchTransformFn = (value: string) => string
|
|||||||
* 3. Trim excess whitespace from left and right.
|
* 3. Trim excess whitespace from left and right.
|
||||||
*
|
*
|
||||||
* 4. Append a wildcard to the end of every word to make every word a prefix
|
* 4. Append a wildcard to the end of every word to make every word a prefix
|
||||||
* query in order to provide a good type-ahead experience, by adding an
|
* query in order to provide a good typeahead experience, by adding an
|
||||||
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
|
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
|
||||||
* any non-control character, or a word boundary.
|
* any non-control character, or a word boundary.
|
||||||
*
|
*
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user