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)
|
||||
|
||||
* 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
|
||||
|
||||
mkdocs-material-5.3.1 (2020-06-20)
|
||||
|
||||
@ -66,27 +66,29 @@ icons and much more:
|
||||
* [Changing colors][3]
|
||||
* [Changing the fonts][4]
|
||||
* [Changing the language][5]
|
||||
* [Navigation][6]
|
||||
* [Syntax highlighting][7]
|
||||
* [Adding a landing page][8]
|
||||
* [Adding an announcement bar][9]
|
||||
* [Adding icons and emojis][10]
|
||||
* [Adding footer links][11]
|
||||
* [Adding site analytics][12]
|
||||
* [Adding a comment system][13]
|
||||
* [Setting up navigation][6]
|
||||
* [Setting up site search][7]
|
||||
* [Adding a git repository][8]
|
||||
* [Adding icons and emojis][9]
|
||||
* [Adding footer links][10]
|
||||
* [Adding site analytics][11]
|
||||
* [Adding a comment system][12]
|
||||
* [Adding an announcement bar][13]
|
||||
* [Adding a landing page][14]
|
||||
|
||||
[2]: getting-started.md#installation
|
||||
[3]: guides/changing-colors.md
|
||||
[4]: guides/changing-the-fonts.md
|
||||
[5]: guides/changing-the-language.md
|
||||
[6]: guides/navigation.md
|
||||
[7]: guides/syntax-highlighting.md
|
||||
[8]: guides/adding-a-landing-page.md
|
||||
[9]: guides/adding-an-announcement-bar.md
|
||||
[10]: guides/adding-icons-and-emojis.md
|
||||
[11]: guides/adding-footer-links.md
|
||||
[12]: guides/adding-site-analytics.md
|
||||
[13]: guides/adding-a-comment-system.md
|
||||
[6]: guides/setting-up-navigation.md
|
||||
[7]: guides/setting-up-site-search.md
|
||||
[8]: guides/adding-a-git-repository.md
|
||||
[9]: guides/adding-icons-and-emojis.md
|
||||
[10]: guides/adding-footer-links.md
|
||||
[11]: guides/adding-site-analytics.md
|
||||
[12]: guides/adding-a-comment-system.md
|
||||
[13]: guides/adding-an-announcement-bar.md
|
||||
[14]: guides/adding-a-landing-page.md
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
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]: assets/guides/creating-your-site.png
|
||||
[15]: http://localhost:8000
|
||||
[16]: assets/guides/creating-your-site.png
|
||||
|
||||
## Building your site
|
||||
|
||||
@ -130,8 +132,8 @@ mkdocs build
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
[16]: publishing-your-site.md#github-pages
|
||||
[17]: publishing-your-site.md#gitlab-pages
|
||||
[17]: publishing-your-site.md#github-pages
|
||||
[18]: publishing-your-site.md#gitlab-pages
|
||||
|
||||
@ -101,7 +101,7 @@ The directory layout of the theme is as follows:
|
||||
│ ├─ javascripts/ # JavaScript
|
||||
│ └─ stylesheets/ # Stylesheets
|
||||
├─ partials/
|
||||
│ ├─ integrations/ # 3rd-party integrations
|
||||
│ ├─ integrations/ # Third-party integrations
|
||||
│ ├─ language/ # Localized languages
|
||||
│ ├─ footer.html # Footer 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
|
||||
|
||||
[: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
|
||||
called `default`, and a dark mode, which is called `slate`. The color scheme
|
||||
@ -62,7 +62,7 @@ theme:
|
||||
|
||||
### 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
|
||||
other components. In order to change the primary color, set the following value
|
||||
@ -117,7 +117,7 @@ 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.
|
||||
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
|
||||
@ -184,9 +184,12 @@ color:
|
||||
|
||||
## 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
|
||||
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:
|
||||
|
||||
``` 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
|
||||
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
|
||||
[7]: ../customization.md#additional-stylesheets
|
||||
[8]: ../extensions/codehilite.md
|
||||
[9]: ../extensions/admonition.md
|
||||
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss
|
||||
[7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
|
||||
[8]: ../customization.md#additional-stylesheets
|
||||
[9]: ../writing/code-blocks.md
|
||||
[10]: ../writing/admonitions.md
|
||||
|
||||
@ -15,7 +15,8 @@ should be used.
|
||||
|
||||
### 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
|
||||
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
|
||||
|
||||
[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default:
|
||||
[`Roboto Mono`][4]
|
||||
[:octicons-file-code-24: Source][2] ·
|
||||
:octicons-milestone-24: Default: [`Roboto Mono`][4]
|
||||
|
||||
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
|
||||
@ -53,6 +54,9 @@ The typeface will be loaded in 400.
|
||||
|
||||
## 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
|
||||
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, add the following lines
|
||||
to `mkdocs.yml`:
|
||||
|
||||
@ -12,7 +12,7 @@ search can be configured to use a language-specific stemmer (if available).
|
||||
|
||||
### 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:
|
||||
|
||||
@ -23,18 +23,6 @@ theme:
|
||||
|
||||
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">
|
||||
<li><code>af</code> / Afrikaans</li>
|
||||
<li><code>ar</code> / Arabic</li>
|
||||
@ -90,22 +78,22 @@ The following languages are supported:
|
||||
|
||||
### Site search language
|
||||
|
||||
[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: automatically
|
||||
set
|
||||
[:octicons-file-code-24: Source][2] ·
|
||||
:octicons-milestone-24: Default: _automatically set_
|
||||
|
||||
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
|
||||
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
|
||||
[3]: https://github.com/MihaiValentin/lunr-languages
|
||||
[4]: ../plugins/search.md#language
|
||||
[4]: setting-up-site-search.md
|
||||
|
||||
|
||||
### Directionality
|
||||
|
||||
[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: automatically
|
||||
set
|
||||
[:octicons-file-code-24: Source][5] ·
|
||||
:octicons-milestone-24: Default: _automatically set_
|
||||
|
||||
While many languages are read `ltr` (left-to-right), Material for MkDocs also
|
||||
supports `rtl` (right-to-left) directionality which is inferred from the
|
||||
@ -140,6 +128,9 @@ directionality:
|
||||
|
||||
## 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,
|
||||
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
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Navigation
|
||||
# Setting up navigation
|
||||
|
||||
A clear and concise navigation structure is an important aspect of good project
|
||||
documentation. Material for MkDocs provides several options to configure the
|
||||
@ -103,10 +103,10 @@ customize its appearance:
|
||||
|
||||
`permalink`
|
||||
|
||||
: This option adds an anchor link containing the paragraph symbol `¶` or
|
||||
another custom symbol at the end of each headline, exactly like on the page
|
||||
you're currently viewing, which Material for MkDocs will make appear on
|
||||
hover:
|
||||
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
|
||||
containing the paragraph symbol `¶` or another custom symbol at the end of
|
||||
each headline, exactly like on the page you're currently viewing, which
|
||||
Material for MkDocs will make appear on hover:
|
||||
|
||||
=== "¶"
|
||||
|
||||
@ -126,10 +126,10 @@ customize its appearance:
|
||||
|
||||
`slugify`
|
||||
|
||||
: This option allows for customization of the slug function. For some
|
||||
languages, the standard slug function may not produce good and readable
|
||||
identifiers. Consider using another slug function like for example those
|
||||
from [Python Markdown Extensions][8]:
|
||||
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
|
||||
customization of the slug function. For some languages, the default may not
|
||||
produce good and readable identifiers. Consider using another slug function
|
||||
like for example those from [Python Markdown Extensions][8]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
@ -149,10 +149,10 @@ customize its appearance:
|
||||
|
||||
`toc_depth`
|
||||
|
||||
: Define the range of levels to be included in the table of contents. This is
|
||||
especially useful for project documentation with deeply structured headings
|
||||
to decrease the length of the table of contents, or to remove the table of
|
||||
contents altogether:
|
||||
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
|
||||
included in the table of contents. This may be useful for project
|
||||
documentation with deeply structured headings to decrease the length of the
|
||||
table of contents, or to remove the table of contents altogether:
|
||||
|
||||
=== "Hide levels 4-6"
|
||||
|
||||
@ -181,10 +181,14 @@ them at your own risk._
|
||||
|
||||
## 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
|
||||
[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`.
|
||||
|
||||
[9]: ../customization.md#extending-the-theme
|
||||
[10]: ../customization.md#overriding-partials
|
||||
[11]: ../customization.md#overriding-blocks
|
||||
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials
|
||||
[10]: ../customization.md#extending-the-theme
|
||||
[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>
|
||||
|
||||
* 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
|
||||
|
||||
### 5.3.1 <small>_ June 20, 2020</small>
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Syntax highlighting
|
||||
# Code blocks
|
||||
|
||||
Code blocks and examples are an essential part of technical project
|
||||
documentation. Material for MkDocs provides different ways to set up syntax
|
||||
@ -23,11 +23,11 @@ configuring syntax highlighting of code blocks:
|
||||
|
||||
`use_pygments`
|
||||
|
||||
: This option allows to control whether highlighting should be carried out
|
||||
during build time by [Pygments][1] (default, recommended) or runtime with
|
||||
a JavaScript highlighter. Remember to add the necessary
|
||||
[additional stylesheets][5] and [JavaScript][6] if you want to use the
|
||||
latter:
|
||||
: :octicons-milestone-24: Default: `true` · This option allows to control
|
||||
whether highlighting should be carried out during build time by
|
||||
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
|
||||
necessary [additional stylesheets][5] and [JavaScript][6] if you want to
|
||||
use the latter:
|
||||
|
||||
=== "Pygments"
|
||||
|
||||
@ -72,10 +72,10 @@ configuring syntax highlighting of code blocks:
|
||||
|
||||
`linenums`
|
||||
|
||||
: This option will add line numbers to _all_ code blocks. If you wish to add
|
||||
line numbers to _some_, but not all code blocks, consult the section on
|
||||
[adding line numbers][9] later in this document, which also contains some
|
||||
tips on working with line numbers:
|
||||
: :octicons-milestone-24: Default: `false` · This option will add line numbers
|
||||
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
|
||||
code blocks, consult the section on [adding line numbers][9] later in this
|
||||
document, which also contains some tips on working with line numbers:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -85,10 +85,10 @@ configuring syntax highlighting of code blocks:
|
||||
|
||||
`linenums_style`
|
||||
|
||||
: The Highlight extension provides three ways to add line numbers, all of
|
||||
which are supported by Material for MkDocs. While `table` (default,
|
||||
recommended) wraps a code block in a table, `inline` and `pymdownx.inline`
|
||||
render line numbers as part of the line itself:
|
||||
: :octicons-milestone-24: Default: `table` · The Highlight extension provides
|
||||
three ways to add line numbers, all of which are supported by Material for
|
||||
MkDocs. While `table` wraps a code block in a table, `inline` and
|
||||
`pymdownx.inline` render line numbers as part of the line itself:
|
||||
|
||||
``` yaml
|
||||
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/
|
||||
[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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
_Example_:
|
||||
@ -168,7 +160,7 @@ _Result_:
|
||||
import tensorflow as tf
|
||||
```
|
||||
|
||||
[13]: https://pygments.org/docs/lexers/
|
||||
[12]: https://pygments.org/docs/lexers/
|
||||
|
||||
### Adding line numbers
|
||||
|
||||
@ -233,7 +225,7 @@ def bubble_sort(items):
|
||||
|
||||
### 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
|
||||
the language short name.
|
||||
|
||||
@ -247,4 +239,4 @@ _Result_:
|
||||
|
||||
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.map": "assets/javascripts/bundle.b49b2592.min.js.map",
|
||||
"assets/javascripts/bundle.js": "assets/javascripts/bundle.1b3af799.min.js",
|
||||
"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.map": "assets/javascripts/vendor.877163d5.min.js.map",
|
||||
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
|
||||
|
||||
@ -183,7 +183,7 @@
|
||||
</div>
|
||||
{% block scripts %}
|
||||
<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 = {} -%}
|
||||
{%- for key in [
|
||||
"clipboard.copy",
|
||||
|
||||
16
mkdocs.yml
16
mkdocs.yml
@ -131,12 +131,14 @@ nav:
|
||||
- Customization: customization.md
|
||||
- Troubleshooting: troubleshooting.md
|
||||
- Data privacy: data-privacy.md
|
||||
- Writing:
|
||||
- Code blocks: writing/code-blocks.md
|
||||
- Guides:
|
||||
- Changing colors: guides/changing-colors.md
|
||||
- Changing the fonts: guides/changing-the-fonts.md
|
||||
- Changing the language: guides/changing-the-language.md
|
||||
- Navigation: guides/navigation.md
|
||||
- Syntax highlighting: guides/syntax-highlighting.md
|
||||
- Setting up navigation: guides/setting-up-navigation.md
|
||||
- Setting up site search: guides/setting-up-site-search.md
|
||||
- Adding a git repository: guides/adding-a-git-repository.md
|
||||
- Adding icons and emojis: guides/adding-icons-and-emojis.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 an announcement bar: guides/adding-an-announcement-bar.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:
|
||||
- Upgrading to 5.x: releases/5.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.
|
||||
*
|
||||
* 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,
|
||||
* any non-control character, or a word boundary.
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user