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
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.
|
||||
*
|
||||
|
||||
@ -50,7 +50,7 @@ export interface SearchSetupMessage {
|
||||
* A message indicating the search index is ready
|
||||
*/
|
||||
export interface SearchReadyMessage {
|
||||
type: SearchMessageType.READY /* Message type */
|
||||
type: SearchMessageType.READY /* Message type */
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user