OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
squidfunk 2021-10-10 12:19:14 +02:00
parent 02b009dcaf
commit b6cd73e083
27 changed files with 407 additions and 402 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/customization.md
View File

@ -39,7 +39,7 @@ extra_css:
``` ```
Spin up the [live preview server][2] and start typing your changes in your Spin up the [live preview server][2] and start typing your changes in your
additional stylesheet file – you should see them almost instantly after saving. additional style sheet file – you should see them almost instantly after saving.
[2]: creating-your-site.md#previewing-as-you-write [2]: creating-your-site.md#previewing-as-you-write

32
docs/insiders/getting-started.md
View File

@ -21,10 +21,10 @@ In order to access the Insiders repository programmatically (from the command
line or GitHub Actions workflows), you need to create a [personal access line or GitHub Actions workflows), you need to create a [personal access
token][4]: token][4]:
1. Go to https://github.com/settings/tokens 1. Go to https://github.com/settings/tokens
2. Click on [Generate a new token][5] 2. Click on [Generate a new token][5]
3. Enter a name and select the [`repo`][6] scope 3. Enter a name and select the [`repo`][6] scope
4. Generate the token and store it in a safe place 4. Generate the token and store it in a safe place
[4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token [4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[5]: https://github.com/settings/tokens/new [5]: https://github.com/settings/tokens/new
@ -52,18 +52,18 @@ additional steps are necessary. While we cannot provide a hosted Docker image
for Insiders[^1], [GitHub Container Registry][7] allows for simple and for Insiders[^1], [GitHub Container Registry][7] allows for simple and
comfortable self-hosting: comfortable self-hosting:
1. [Fork the Insiders repository][8] 1. [Fork the Insiders repository][8]
2. Enable [GitHub Actions][9] on your fork[^2] 2. Enable [GitHub Actions][9] on your fork[^2]
3. Create a new personal access token[^3] 3. Create a new personal access token[^3]
1. Go to https://github.com/settings/tokens 1. Go to https://github.com/settings/tokens
2. Click on [Generate a new token][5] 2. Click on [Generate a new token][5]
3. Enter a name and select the [`write:packages`][10] scope 3. Enter a name and select the [`write:packages`][10] scope
4. Generate the token and store it in a safe place 4. Generate the token and store it in a safe place
4. Add a [GitHub Actions secret][11] on your fork 4. Add a [GitHub Actions secret][11] on your fork
1. Set the name to `GHCR_TOKEN` 1. Set the name to `GHCR_TOKEN`
2. Set the value to the personal access token created in the previous step 2. Set the value to the personal access token created in the previous step
5. [Create a new release][12] to build and publish the Docker image 5. [Create a new release][12] to build and publish the Docker image
6. Install [Pull App][13] on your fork to stay in-sync with upstream 6. Install [Pull App][13] on your fork to stay in-sync with upstream
The [`publish`][14] workflow[^4] is automatically run when a new tag (release) The [`publish`][14] workflow[^4] is automatically run when a new tag (release)
is created. When a new Insiders version is released on the upstream repository, is created. When a new Insiders version is released on the upstream repository,

4
docs/reference/abbreviations.md
View File

@ -4,7 +4,7 @@ template: overrides/main.html
# Abbreviations # Abbreviations
Technical documentation often incurs the usage of a lot of acronyms, which may Technical documentation often incurs the usage of many acronyms, which may
need additional explanation, especially for new user of your project. For these need additional explanation, especially for new user of your project. For these
matters, Material for MkDocs uses a combination of Markdown extensions to matters, Material for MkDocs uses a combination of Markdown extensions to
enable site-wide glossaries. enable site-wide glossaries.
@ -69,7 +69,7 @@ all abbreviations in a dedicated file[^1], and embedding it with the
_Example_: _Example_:
=== ":octicons-file-code-16: docs/page.md" === ":octicons-file-code-16: docs/example.md"
```` markdown ```` markdown
The HTML specification is maintained by the W3C. The HTML specification is maintained by the W3C.

82
docs/reference/admonitions.md
View File

@ -404,37 +404,9 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
### Custom admonitions ### Custom admonitions
[:octicons-file-code-24: Source][Source] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to add a custom admonition type, all you need is a color and an If you want to add a custom admonition type, all you need is a color and an
`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder `*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
and add the following CSS to an [additional stylesheet]: and add the following CSS to an [additional style sheet]:
``` css
:root {
--md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
background-color: rgba(43, 155, 70, 0.1);
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
background-color: rgb(43, 155, 70);
-webkit-mask-image: var(--md-admonition-icon--pied-piper);
mask-image: var(--md-admonition-icon--pied-piper);
}
```
You should now be able to create an admonition of the `pied-piper` type. Note
that you can also use this technique to override existing admonition icons or
colors. [You can even add animations][Custom animations].
<style> <style>
:root { :root {
@ -459,13 +431,45 @@ colors. [You can even add animations][Custom animations].
_Example_: _Example_:
``` markdown === ":octicons-file-code-16: docs/example.md"
!!! pied-piper "Pied Piper"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod ``` markdown
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor !!! pied-piper "Pied Piper"
massa, nec semper lorem quam in massa.
``` 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.
```
=== ":octicons-file-code-16: docs/stylesheets/admonitions.css"
``` css
:root {
--md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
}
.md-typeset .admonition.pied-piper,
.md-typeset details.pied-piper {
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title,
.md-typeset .pied-piper > summary {
background-color: rgba(43, 155, 70, 0.1);
border-color: rgb(43, 155, 70);
}
.md-typeset .pied-piper > .admonition-title::before,
.md-typeset .pied-piper > summary::before {
background-color: rgb(43, 155, 70);
-webkit-mask-image: var(--md-admonition-icon--pied-piper);
mask-image: var(--md-admonition-icon--pied-piper);
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/admonitions.css
```
_Result_: _Result_:
@ -475,7 +479,5 @@ _Result_:
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
[Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_admonition.scss [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[Custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons [additional style sheet]: ../customization.md#additional-css
[Custom animations]: icons-emojis.md#with-animations
[additional stylesheet]: ../customization.md#additional-css

16
docs/reference/buttons.md
View File

@ -30,38 +30,38 @@ See additional configuration options:
### Adding buttons ### Adding buttons
In order to render a link as a button, suffix it with curly braces and add the In order to render a link as a button, suffix it with curly braces and add the
`#!css .md-button` class selector to it. The button will receive the selected `.md-button` class selector to it. The button will receive the selected
[primary color] and [accent color] if active. [primary color] and [accent color] if active.
_Example_: _Example_:
``` markdown ``` markdown
[Don't click me](#){ .md-button } [Subscribe to our newsletter](#){ .md-button }
``` ```
_Result_: _Result_:
[Don't click me][Demo]{ .md-button } [Subscribe to our newsletter][Demo]{ .md-button }
[primary color]: ../setup/changing-the-colors.md#primary-color [primary color]: ../setup/changing-the-colors.md#primary-color
[accent color]: ../setup/changing-the-colors.md#accent-color [accent color]: ../setup/changing-the-colors.md#accent-color
[Demo]: javascript:alert$.next("Hi!") [Demo]: javascript:alert$.next("Demo")
### Adding primary buttons ### Adding primary buttons
If you want to display a filled, primary button (like on the [landing page] If you want to display a filled, primary button (like on the [landing page]
of Material for MkDocs), add both, the `#!css .md-button` and of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
`#!css .md-button--primary` CSS class selectors. CSS class selectors.
_Example_: _Example_:
``` markdown ``` markdown
[Don't click me](#){ .md-button .md-button--primary } [Subscribe to our newsletter](#){ .md-button .md-button--primary }
``` ```
_Result_: _Result_:
[Don't click me][Demo]{ .md-button .md-button--primary } [Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
[landing page]: ../index.md [landing page]: ../index.md

55
docs/reference/code-blocks.md
View File

@ -63,7 +63,7 @@ theme:
If you don't want to enable code annotations globally, because you don't If you don't want to enable code annotations globally, because you don't
like the automatic inlining behavior, you can enable them for a specific like the automatic inlining behavior, you can enable them for a specific
code block by using a slightly different syntax based on the code block by using a slightly different syntax based on the
[Attribute List] extension: [Attribute Lists] extension:
```` yaml ```` yaml
``` { .yaml .annotate } ``` { .yaml .annotate }
@ -75,7 +75,7 @@ theme:
prefixed by a `.`. prefixed by a `.`.
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[Attribute List]: ../setup/extensions/python-markdown.md#attribute-lists [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
## Usage ## Usage
@ -270,11 +270,8 @@ last 4 years
### Custom syntax theme ### Custom syntax theme
[:octicons-file-code-24: Source][Source] ·
:octicons-mortar-board-24: Difficulty: _easy_
If [Pygments] is used, Material for MkDocs provides the [styles for code blocks] If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
[Source], which are built with a custom and well-balanced palette that works [colors], which are built with a custom and well-balanced palette that works
equally well for both [color schemes]: equally well for both [color schemes]:
- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color` - :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
@ -298,26 +295,44 @@ Code block foreground, background and line highlight colors are defined via:
Let's say you want to change the color of `#!js "strings"`. While there are Let's say you want to change the color of `#!js "strings"`. While there are
several [types of string tokens], they use the same color. You can assign several [types of string tokens], they use the same color. You can assign
a new color by using an [additional stylesheet]: a new color by using an [additional style sheet]:
``` css === ":octicons-file-code-16: docs/stylesheets/colors.css"
:root > * {
--md-code-hl-string-color: #0FF1CE; ``` css
} :root > * {
``` --md-code-hl-string-color: #0FF1CE;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/colors.css
```
If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
can lookup the specific CSS class name in the [syntax theme definition], and can lookup the specific CSS class name in the [syntax theme definition], and
override it as part of your [additional stylesheet]: override it as part of your [additional style sheet]:
``` css === ":octicons-file-code-16: docs/stylesheets/colors.css"
.highlight .sb {
color: #0FF1CE;
}
```
[Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss ``` css
.highlight .sb {
color: #0FF1CE;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/colors.css
```
[colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[color schemes]: ../setup/changing-the-colors.md#color-scheme [color schemes]: ../setup/changing-the-colors.md#color-scheme
[types of string tokens]: https://pygments.org/docs/tokens/#literals [types of string tokens]: https://pygments.org/docs/tokens/#literals
[additional stylesheet]: ../customization.md#additional-css [additional style sheet]: ../customization.md#additional-css
[syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss

12
docs/reference/content-tabs.md
View File

@ -52,18 +52,18 @@ tabs with the same label will be activated when a user clicks a content tab
regardless of order inside a container. Furthermore, this feature is fully regardless of order inside a container. Furthermore, this feature is fully
integrated with [instant loading] and persisted across page loads. integrated with [instant loading] and persisted across page loads.
=== "With linking" === ":octicons-check-circle-fill-16: Enabled"
[![With linking]][With linking] [![linking enabled]][linking enabled]
=== "Without linking" === ":octicons-skip-16: Disabled"
[![Without linking]][Without linking] [![linking disabled]][linking disabled]
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[instant loading]: ../setup/setting-up-navigation.md#instant-loading [instant loading]: ../setup/setting-up-navigation.md#instant-loading
[With linking]: ../assets/screenshots/content-tabs-link.png [linking enabled]: ../assets/screenshots/content-tabs-link.png
[Without linking]: ../assets/screenshots/content-tabs.png [linking disabled]: ../assets/screenshots/content-tabs.png
## Usage ## Usage

4
docs/reference/data-tables.md
View File

@ -132,7 +132,7 @@ If you want to make data tables sortable, you can add [tablesort], which is
natively integrated with Material for MkDocs and will also work with [instant natively integrated with Material for MkDocs and will also work with [instant
loading] via [additional JavaScript]: loading] via [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/tables.js" === ":octicons-file-code-16: docs/javascripts/tablesort.js"
``` js ``` js
document$.subscribe(function() { document$.subscribe(function() {
@ -148,7 +148,7 @@ loading] via [additional JavaScript]:
``` yaml ``` yaml
extra_javascript: extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
- javascripts/tables.js - javascripts/tablesort.js
``` ```
Note that [tablesort] provides alternative comparison implementations like Note that [tablesort] provides alternative comparison implementations like

6
docs/reference/diagrams.md
View File

@ -34,8 +34,8 @@ No further configuration is necessary. Advantages over a custom integration:
- [x] Works with [instant loading] without any additional effort - [x] Works with [instant loading] without any additional effort
- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1] - [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
- [x] Fonts and colors can be customized with [additional stylesheets] - [x] Fonts and colors can be customized with [additional style sheets]
- [x] Support for both, light and dark color schemes - [x] Support for both, light and dark color schemes – _try it on this page!_
[^1]: [^1]:
While all [Mermaid.js] features should work out-of-the-box, Material for While all [Mermaid.js] features should work out-of-the-box, Material for
@ -45,7 +45,7 @@ No further configuration is necessary. Advantages over a custom integration:
[Insiders]: ../insiders/index.md [Insiders]: ../insiders/index.md
[instant loading]: ../setup/setting-up-navigation.md#instant-loading [instant loading]: ../setup/setting-up-navigation.md#instant-loading
[additional stylesheets]: ../customization.md#additional-css [additional style sheets]: ../customization.md#additional-css
## Usage ## Usage

14
docs/reference/footnotes.md
View File

@ -4,16 +4,16 @@ template: overrides/main.html
# Footnotes # Footnotes
Footnotes are a great way to add references to supplemental or additional Footnotes are a great way to add supplemental or additional information to a
information to a specific word, phrase or sentence without interrupting the specific word, phrase or sentence without interrupting the flow of a document.
flow of a document. Material for MkDocs provides the ability to define and Material for MkDocs provides the ability to define, reference and render
render footnotes. footnotes.
## Configuration ## Configuration
This configuration adds the ability to define footnotes inline with the content, This configuration adds the ability to define inline footnotes, which are then
which are then rendered below all Markdown content of a document. Add the rendered below all Markdown content of a document. Add the following lines to
following lines to `mkdocs.yml`: `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:

21
docs/reference/formatting.md
View File

@ -13,8 +13,8 @@ for a document.
## Configuration ## Configuration
This configuration enables support for keyboard keys, highlighting changes This configuration enables support for keyboard keys, tracking changes in
to documents, highlighting text and defining sub- and superscript. Add the documents, defining sub- and superscript and highlighting text. Add the
following lines to `mkdocs.yml`: following lines to `mkdocs.yml`:
``` yaml ``` yaml
@ -26,6 +26,8 @@ markdown_extensions:
- pymdownx.tilde - pymdownx.tilde
``` ```
See additional configuration options:
- [Critic] - [Critic]
- [Caret, Mark & Tilde] - [Caret, Mark & Tilde]
- [Keys] - [Keys]
@ -77,8 +79,8 @@ Text can be <del class="critic">deleted</del> and replacement text
### Highlighting text ### Highlighting text
When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
syntax, which is more convenient that directly using the corresponding `mark`, syntax, which is more convenient that directly using the corresponding
`ins` and `del` HTML tags. [`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags.
_Example_: _Example_:
@ -94,11 +96,15 @@ _Result_:
- ^^This was inserted^^ - ^^This was inserted^^
- ~~This was deleted~~ - ~~This was deleted~~
[mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
[ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
[del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
### Sub- and superscripts ### Sub- and superscripts
When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
superscripted with a simple syntax, which is more convenient that directly superscripted with a simple syntax, which is more convenient that directly
using the corresponding `sub` and `sup` HTML tags: using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
_Example_: _Example_:
@ -112,6 +118,9 @@ _Result_:
- H~2~0 - H~2~0
- A^T^A - A^T^A
[sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
[sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
### Adding keyboard keys ### Adding keyboard keys
When [Keys] is enabled, keyboard keys can be rendered with a simple syntax. When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
@ -128,4 +137,4 @@ _Result_:
++ctrl+alt+del++ ++ctrl+alt+del++
[Python Markdown Extensions]: [#keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index) [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index

151
docs/reference/icons-emojis.md
View File

@ -59,7 +59,7 @@ See additional configuration options:
[Octicons]: https://octicons.github.com/ [Octicons]: https://octicons.github.com/
[additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons [additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons
[Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom_icons [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#custom-icons
## Usage ## Usage
@ -86,46 +86,33 @@ _Result_:
When [Emoji] is enabled, icons can be used similar to emojis, by referencing When [Emoji] is enabled, icons can be used similar to emojis, by referencing
a valid path to any icon bundled with the theme, which are located in the a valid path to any icon bundled with the theme, which are located in the
[`.icons`][1] directory, and replacing `/` with `-`: [`.icons`][custom icons] directory, and replacing `/` with `-`:
_Example_: _Example_:
``` ```
- :material-account-circle: – `.icons/material/account-circle.svg` - :material-account-circle: – `material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg` - :fontawesome-regular-laugh-wink: – `fontawesome/regular/laugh-wink.svg`
- :octicons-repo-push-16: – `.icons/octicons/repo-push-16.svg` - :octicons-repo-push-16: – `octicons/repo-push-16.svg`
``` ```
_Result_: _Result_:
- :material-account-circle: – [`.icons/material/account-circle.svg`][14] - :material-account-circle: – [`material/account-circle.svg`][icon Material]
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15] - :fontawesome-regular-laugh-wink: – [`fontawesome/regular/laugh-wink.svg`][icon FontAwesome]
- :octicons-repo-push-16: – [`.icons/octicons/repo-push-16.svg`][16] - :octicons-repo-push-16: – [`octicons/repo-push-16.svg`][icon Octicons]
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg [icon Material]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
[16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg [icon FontAwesome]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
[icon Octicons]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
#### with colors #### with colors
When the [Attribute List][17] extension is enabled, custom CSS classes and When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
attributes can be added to icons by suffixing the icon with a special syntax. suffixing the icon with a special syntax. While HTML allows to use
While HTML and CSS allow to use [inline styles][18], it's always best to add [inline styles], it's always recommended to add an [additional style sheet] and
an [additional stylesheet][19] and put styles into dedicated CSS classes: move declarations into dedicated CSS classes.
``` css
.medium {
color: #00AB6C;
}
.twitter {
color: #1DA1F2;
}
.facebook {
color: #4267B2;
}
```
Then, simply add the CSS class to the icon.
<style> <style>
.medium { .medium {
@ -141,11 +128,34 @@ Then, simply add the CSS class to the icon.
_Example_: _Example_:
``` markdown === ":octicons-file-code-16: docs/example.md"
- :fontawesome-brands-medium:{ .medium } – Medium
- :fontawesome-brands-twitter:{ .twitter } – Twitter ``` markdown
- :fontawesome-brands-facebook:{ .facebook } – Facebook - :fontawesome-brands-medium:{ .medium } – Medium
``` - :fontawesome-brands-twitter:{ .twitter } – Twitter
- :fontawesome-brands-facebook:{ .facebook } – Facebook
```
=== ":octicons-file-code-16: docs/stylesheets/icons.css"
``` css
.medium {
color: #00AB6C;
}
.twitter {
color: #1DA1F2;
}
.facebook {
color: #4267B2;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/icons.css
```
_Result_: _Result_:
@ -153,52 +163,61 @@ _Result_:
- :fontawesome-brands-twitter:{ .twitter } – Twitter - :fontawesome-brands-twitter:{ .twitter } – Twitter
- :fontawesome-brands-facebook:{ .facebook } – Facebook - :fontawesome-brands-facebook:{ .facebook } – Facebook
[17]: #attribute-list [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
[18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style [inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
[19]: ../customization.md#additional-css [additional style sheet]: ../customization.md#additional-css
#### with animations #### with animations
Similar to adding [colors][20], it's just as easy to add [CSS animations][21] to Similar to adding [colors], it's just as easy to add [animations] to icons by
icons by using an [additional stylesheet][6], defining a `#!css @keyframes` rule using an [additional style sheet], defining a `@keyframes` rule and adding a
and adding the dedicated CSS class to the icon: dedicated CSS class to the icon.
``` css
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
.heart {
animation: heart 1000ms infinite;
}
```
Then, simply add the CSS class to the icon.
_Example_: _Example_:
``` markdown === ":octicons-file-code-16: docs/example.md"
:octicons-heart-fill-24:{ .heart }
``` ``` markdown
:octicons-heart-fill-24:{ .heart }
```
=== ":octicons-file-code-16: docs/stylesheets/icons.css"
``` css
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
.heart {
animation: heart 1000ms infinite;
}
```
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml
extra_css:
- stylesheets/icons.css
```
_Result_: _Result_:
:octicons-heart-fill-24:{ .mdx-heart } :octicons-heart-fill-24:{ .mdx-heart }
[20]: #with-colors [colors]: #with-colors
[21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
## Customization ## Customization
### Using icons in templates ### Using icons in templates
When you're [extending the theme][22] with partials or blocks, you can simply When you're [extending the theme] with partials or blocks, you can simply
reference any icon that's [bundled with the theme][1] with Jinja's reference any icon that's [bundled with the theme][icon search] with Jinja's
[`include`][23] function and wrap it with the `twemoji` class: [`include`][include] function and wrap it with the `.twemoji` CSS class:
``` html ``` html
<span class="twemoji"> <span class="twemoji">
@ -208,5 +227,5 @@ reference any icon that's [bundled with the theme][1] with Jinja's
This is exactly what Material for MkDocs does in its templates. This is exactly what Material for MkDocs does in its templates.
[22]: ../customization.md#extending-the-theme [extending the theme]: ../customization.md#extending-the-theme
[23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include [include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include

62
docs/reference/images.md
View File

@ -6,32 +6,36 @@ template: overrides/main.html
While images are first-class citizens of Markdown and part of the core syntax, While images are first-class citizens of Markdown and part of the core syntax,
it can be difficult to work with them. Material for MkDocs makes working with it can be difficult to work with them. Material for MkDocs makes working with
images more comfortable by providing styles for alignment and image captions. images more comfortable, providing styles for image alignment and image
captions.
[1]: https://www.markdownguide.org/basic-syntax/#images-1
## Configuration ## Configuration
### Attribute List This configuration adds the ability to align images, add captions to images
(rendering them as figures), and mark large images for lazy-loading. Add the
The [Attribute List][2] extension, which is part of the standard Markdown following lines to `mkdocs.yml`:
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- attr_list - attr_list
- md_in_html
``` ```
[2]: https://python-markdown.github.io/extensions/attr_list/ See additional configuration options:
- [Attribute Lists]
- [Markdown in HTML]
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
## Usage ## Usage
### Image alignment ### Image alignment
When the [Attribute List][3] extension is enabled, images can be aligned by When [Attribute Lists] is enabled, images can be aligned by adding the
adding the respective alignment directions via the `align` attribute, i.e. respective alignment directions via the `align` attribute, i.e. `align=left` or
`align=left` or `align=right` `align=right`:
=== "Left" === "Left"
@ -65,15 +69,31 @@ adding the respective alignment directions via the `align` attribute, i.e.
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa. massa, nec semper lorem quam in massa.
_If there's insufficient space to render the text next to the image, the image If there's insufficient space to render the text next to the image, the image
will stretch to the full width of the viewport, e.g. on mobile viewports._ will stretch to the full width of the viewport, e.g. on mobile viewports.
[3]: #attribute-list ??? question "Why is there no centered alignment?"
The [`align`][align] attribute doesn't allow for centered alignment, which
is why this option is not supported by Material for MkDocs.[^1] Instead,
the [image captions] syntax can be used, as captions are optional.
[^1]:
You might also realize that the [`align`][align] attribute has been
deprecated as of HTML5, so why use it anyways? The main reason is
portability – it's still supported by all browsers and clients, and is very
unlikely to be completely removed, as many older websites still use it. This
ensures a consistent appearance when a Markdown file with these attributes
is viewed outside of a website generated by Material for MkDocs.
[align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes
[image captions]: #image-captions
### Image captions ### Image captions
Sadly, the Markdown syntax doesn't provide native support for image captions, Sadly, the Markdown syntax doesn't provide native support for image captions,
but it's always possible to resort to HTML. Using `figure` and `figcaption`, captions can be added to images. but it's always possible to use HTML. Using `figure` and `figcaption`, captions
can be added to images.
_Example_: _Example_:
@ -98,10 +118,9 @@ _Result_:
### Image lazy-loading ### Image lazy-loading
Modern browsers provide [native support for lazy-loading images][4] through the Modern browsers provide [native support for lazy-loading images][lazy-loading]
`loading` attribute, which degrades to eager-loading in browsers without through the `loading=lazy` directive, which degrades to eager-loading in
support. As with [image alignment][5], if the [Attribute List][3] extension is browsers without support
enabled, images can be lazy-loaded by adding `loading=lazy`.
_Example_: _Example_:
@ -113,5 +132,4 @@ _Result_:
![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ loading=lazy width=300 } ![Placeholder](https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–){ loading=lazy width=300 }
[4]: https://caniuse.com/#feat=loading-lazy-attr [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
[5]: #image-alignment

122
docs/reference/lists.md
View File

@ -11,64 +11,31 @@ are supported through extensions.
## Configuration ## Configuration
### Definition List This configuration enables the use of definition lists and tasks lists, which
are both not part of the standard Markdown syntax. Add the following lines to
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] `mkdocs.yml`:
The [Definition List][2] extension, which is part of the standard Markdown
library, adds the ability to add definitions lists to a document and can be
enabled via `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- def_list - def_list
- pymdownx.tasklist:
custom_checkbox: true
``` ```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss See additional configuration options:
[2]: https://python-markdown.github.io/extensions/definition_lists/
### Tasklist - [Definition Lists]
- [Tasklist]
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4] [Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists
[Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist
The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5],
adds support for lists with styled checkboxes, and provides several options for
configuring the style:
`custom_checkbox`{ #custom-checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
custom_checkbox: true
```
`clickable_checkbox`{ #clickable-checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this
option is _rather discouraged_ from a user experience perspective:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
clickable_checkbox: true
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tasklist.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[5]: https://facelessuser.github.io/pymdown-extensions/
## Usage ## Usage
### Using unordered lists ### Using unordered lists
An unordered list can be written by prefixing a line with a `-`, `*` or `+` Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
list marker, all of which can be used interchangeably. Furthermore, all flavors marker, all of which can be used interchangeably. Furthermore, all flavors
of lists can be nested inside each other. of lists can be nested inside each other.
_Example_: _Example_:
@ -95,60 +62,61 @@ _Result_:
### Using ordered lists ### Using ordered lists
An ordered list must start with a number immediately followed by a dot. The Ordered lists must start with a number immediately followed by a dot. The
numbers do not need to be consecutive and can be all set to `1.`, as they will numbers do not need to be consecutive and can be all set to `1.`, as they will
be re-numbered when rendered. be re-numbered when rendered.
_Example_: _Example_:
``` markdown ``` markdown
1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis 1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo. nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed. ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
1. Mauris dictum mi lacus 1. Mauris dictum mi lacus
2. Ut sit amet placerat ante 2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu 3. Suspendisse ac eros arcu
``` ```
_Result_: _Result_:
1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis 1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo. nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed. ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
1. Mauris dictum mi lacus 1. Mauris dictum mi lacus
2. Ut sit amet placerat ante 2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu 3. Suspendisse ac eros arcu
### Using definition lists ### Using definition lists
[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g. When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
the parameters of functions or modules, as used within this documentation to parameters of functions or modules, can be enumerated with a simple syntax.
describe extension or plugin parameters.
_Example_: _Example_:
``` markdown ``` markdown
`Lorem ipsum dolor sit amet` `Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus : Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis. tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero` `Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin : Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante. ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
@ -160,10 +128,12 @@ _Example_:
_Result_: _Result_:
`Lorem ipsum dolor sit amet` `Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus : Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis. tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero` `Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin : Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante. ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
@ -171,13 +141,11 @@ _Result_:
Nam vulputate tincidunt fringilla. Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor. Nullam dignissim ultrices urna non auctor.
[6]: #definition-list
### Using task lists ### Using task lists
When the [Tasklist][7] extension is enabled, unordered list items can be When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
prefixed with `[ ]` to render an unchecked or `[x]` to render a checked render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
checkbox. for the definition of task lists.
_Example_: _Example_:
@ -198,5 +166,3 @@ _Result_:
* [x] In scelerisque nibh non dolor mollis congue sed et metus * [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa * [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque - [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
[7]: #tasklist

67
docs/reference/mathjax.md
View File

@ -4,37 +4,23 @@ template: overrides/main.html
# MathJax # MathJax
[MathJax][1] is a beautiful and accessible way to display _mathematical content_ [MathJax] is a beautiful and accessible way to display mathematical content
in the browser, allows for writing formulas in different notations, including in the browser, adds support for mathematical typesetting in different notations
[LaTeX][2], [MathML][3] and [AsciiMath][4], and can be easily integrated with (e.g. [LaTeX], [MathML], [AsciiMath]), and can be easily integrated with
Material for MkDocs. Material for MkDocs.
[1]: https://www.mathjax.org/ [MathJax]: https://www.mathjax.org/
[2]: https://en.wikibooks.org/wiki/LaTeX/Mathematics [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
[3]: https://en.wikipedia.org/wiki/MathML [MathML]: https://en.wikipedia.org/wiki/MathML
[4]: http://asciimath.org/ [AsciiMath]: http://asciimath.org/
## Configuration ## Configuration
### Arithmatex This configuration enables support for rendering block and inline block
equations through [MathJax]. Create a configuration file and add the following
lines to `mkdocs.yml`:
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6] === ":octicons-file-code-16: docs/javascripts/mathjax.js"
The [Arithmatex][6] extension, which is part of of [Python Markdown
Extensions][7], allows the rendering of block and inline block equations, and
can be enabled via `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
```
Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with [additional
JavaScript][8]:
=== "docs/javascripts/config.js"
``` js ``` js
window.MathJax = { window.MathJax = {
@ -50,31 +36,32 @@ JavaScript][8]:
} }
}; };
document$.subscribe(() => { document$.subscribe(() => { // (1)
MathJax.typesetPromise() MathJax.typesetPromise()
}) })
``` ```
=== "mkdocs.yml" 1. This integrates MathJax with [instant loading].
=== ":octicons-file-code-16: mkdocs.yml"
``` yaml ``` yaml
markdown_extensions:
- pymdownx.arithmatex:
generic: true
extra_javascript: extra_javascript:
- javascripts/config.js - javascripts/mathjax.js
- https://polyfill.io/v3/polyfill.min.js?features=es6 - https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
``` ```
_MathJax can be configured in many different ways, for which Material for MkDocs See additional configuration options:
might not provide native support. See the [official documentation][6] for more
information._
!!! tip "Using MathJax with [instant loading][9]" - [Arithmatex]
There's no additional effort necessary to integrate _MathJax 3_ with [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
[instant loading][9] – it's expected to work straight away. However, a [instant loading]: ../setup/setting-up-navigation.md#instant-loading
previous version of this document explained how to integrate Material for
MkDocs with _MathJax 2_, which doesn't exhibit this behavior. It's therefore
highly recommended to switch to _MathJax 3_.
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script> <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
@ -93,12 +80,6 @@ information._
}; };
</script> </script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_arithmatex.scss
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/
[8]: ../customization.md#additional-javascript
[9]: ../setup/setting-up-navigation.md#instant-loading
## Usage ## Usage
### Using block syntax ### Using block syntax

6
docs/setup/adding-a-git-repository.md
View File

@ -121,7 +121,7 @@ plugins:
The following options are supported: The following options are supported:
`enabled_if_env`{ #enabled_if_env } `enabled_if_env`{ #enabled-if-env }
: :octicons-milestone-24: Default: _none_ – When specified the data will only be extracted from git : :octicons-milestone-24: Default: _none_ – When specified the data will only be extracted from git
if the environment variable exists. This makes it possible to disable if the environment variable exists. This makes it possible to disable
@ -174,7 +174,7 @@ The following options are supported:
type: date type: date
``` ```
`fallback_to_build_date`{ #fallback_to_build_date } `fallback_to_build_date`{ #fallback-to-build-date }
: :octicons-milestone-24: Default: `false` – Enables falling back to : :octicons-milestone-24: Default: `false` – Enables falling back to
the time when `mkdocs build` was executed. Can be used as a fallback when the time when `mkdocs build` was executed. Can be used as a fallback when
@ -186,7 +186,7 @@ The following options are supported:
fallback_to_build_date: true fallback_to_build_date: true
``` ```
`enable_creation_date`{ #enable_creation_date } `enable_creation_date`{ #enable-creation-date }
: :octicons-milestone-24: Default: `false` – Enables the display of the : :octicons-milestone-24: Default: `false` – Enables the display of the
_created at_ date of the file associated with the page next to the _created at_ date of the file associated with the page next to the

2
docs/setup/changing-the-colors.md
View File

@ -252,7 +252,7 @@ default color palette.
Material for MkDocs implements colors using [CSS variables][12] (custom Material for MkDocs implements colors using [CSS variables][12] (custom
properties). If you want to customize the colors beyond the palette (e.g. to properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional stylesheet][13] and use your brand-specific colors), you can add an [additional style sheet][13] and
tweak the values of the CSS variables. tweak the values of the CSS variables.
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" } Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }

2
docs/setup/changing-the-fonts.md
View File

@ -77,7 +77,7 @@ theme:
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
If you want to load an (additional) font from another or override If you want to load an (additional) font from another or override
the fallback font, you can use an [additional stylesheet][8] to add the the fallback font, you can use an [additional style sheet][8] to add the
corresponding `@font-face` definition: corresponding `@font-face` definition:
``` css ``` css

42
docs/setup/extensions/python-markdown-extensions.md
View File

@ -5,7 +5,7 @@ template: overrides/main.html
# Python Markdown Extensions # Python Markdown Extensions
The [Python Markdown Extensions] package is an excellent collection of The [Python Markdown Extensions] package is an excellent collection of
additional Markdown extensions that make technical writing a breeze. Material additional extensions perfectly suited for advanced technical writing. Material
for MkDocs lists this package as an explicit dependency, so it's automatically for MkDocs lists this package as an explicit dependency, so it's automatically
installed with a supported version. installed with a supported version.
@ -37,7 +37,7 @@ Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
the JavaScript runtime need to be included, which can be done with a few lines the JavaScript runtime need to be included, which can be done with a few lines
of [additional JavaScript]: of [additional JavaScript]:
=== ":octicons-file-code-16: docs/javascripts/config.js" === ":octicons-file-code-16: docs/javascripts/mathjax.js"
``` js ``` js
window.MathJax = { window.MathJax = {
@ -62,7 +62,7 @@ of [additional JavaScript]:
``` yaml ``` yaml
extra_javascript: extra_javascript:
- javascripts/config.js - javascripts/mathjax.js
- https://polyfill.io/v3/polyfill.min.js?features=es6 - https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
``` ```
@ -237,7 +237,7 @@ markdown_extensions:
The following configuration options are supported: The following configuration options are supported:
`emoji_index`{ #emoji_index } `emoji_index`{ #emoji-index }
: :octicons-milestone-24: Default: `emojione` – This option defines which set : :octicons-milestone-24: Default: `emojione` – This option defines which set
of emojis is used for rendering. Note that the use of `emojione` is not of emojis is used for rendering. Note that the use of `emojione` is not
@ -249,7 +249,7 @@ The following configuration options are supported:
emoji_index: !!python/name:materialx.emoji.twemoji emoji_index: !!python/name:materialx.emoji.twemoji
``` ```
`emoji_generator`{ #emoji_generator } `emoji_generator`{ #emoji-generator }
: :octicons-milestone-24: Default: `to_png` – This option defines how the : :octicons-milestone-24: Default: `to_png` – This option defines how the
resolved emoji or icon shortcode is render. Note that icons can only be resolved emoji or icon shortcode is render. Note that icons can only be
@ -261,10 +261,10 @@ The following configuration options are supported:
emoji_generator: !!python/name:materialx.emoji.to_svg emoji_generator: !!python/name:materialx.emoji.to_svg
``` ```
`options.custom_icons`{ #custom_icons } `options.custom_icons`{ #custom-icons }
: :octicons-milestone-24: Default: _none_ – This option allows to list folders : :octicons-milestone-24: Default: _none_ – This option allows to list folders
with additional icon sets to be used in Markdown documents, which is with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
explained in more detail in the [icon customization guide]. explained in more detail in the [icon customization guide].
``` yaml ``` yaml
@ -315,17 +315,13 @@ markdown_extensions:
perform syntax highlighting on code blocks, not the other way round, which perform syntax highlighting on code blocks, not the other way round, which
is why this extension also needs to be enabled. is why this extension also needs to be enabled.
However, this only applies for when [Pygments] is used. If you use a
JavaScript syntax highlighter, [SuperFences][SuperFences #] might not
be necessary, but it's strongly recommended anyway.
The following configuration options are supported: The following configuration options are supported:
`use_pygments`{ #use-pygments } `use_pygments`{ #use-pygments }
: :octicons-milestone-24: Default: `true` – This option allows to control : :octicons-milestone-24: Default: `true` – This option allows to control
whether highlighting should be carried out during build time using whether highlighting should be carried out during build time using
[Pygments] or runtime with a JavaScript syntax highlighter: [Pygments] or in the browser with a JavaScript syntax highlighter:
=== "Pygments" === "Pygments"
@ -348,7 +344,7 @@ The following configuration options are supported:
integrated with some [additional JavaScript] and [CSS][additional CSS] integrated with some [additional JavaScript] and [CSS][additional CSS]
in `mkdocs.yml`: in `mkdocs.yml`:
=== ":octicons-file-code-16: docs/javascripts/config.js" === ":octicons-file-code-16: docs/javascripts/highlight.js"
``` js ``` js
document$.subscribe(() => { document$.subscribe(() => {
@ -361,7 +357,7 @@ The following configuration options are supported:
``` yaml ``` yaml
extra_javascript: extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
- javascripts/config.js - javascripts/highlight.js
extra_css: extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
``` ```
@ -547,7 +543,7 @@ markdown_extensions:
The following configuration options are supported: The following configuration options are supported:
`custom_fences`{ #custom_fences } `custom_fences`{ #custom-fences }
: :octicons-milestone-24: Default: _none_ – This option allows to define a : :octicons-milestone-24: Default: _none_ – This option allows to define a
handler for custom fences, e.g. to preserve the definitions of [Mermaid.js] handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
@ -606,12 +602,12 @@ markdown_extensions:
The following configuration options are supported: The following configuration options are supported:
`alternate_style`{ #alternate_style } `alternate_style`{ #alternate-style }
: :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1] : :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1]
[Tabbed alternate support] – This option enables the [alternate style] of [Tabbed alternate support] – This option enables the [alternate style] of
content tabs, which has [better behavior on smaller screen sizes], and thus content tabs, which has [better behavior on mobile viewports], and thus
is _strongly recommended_: is strongly recommended:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -633,7 +629,7 @@ See reference for usage:
[Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0 [Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
[Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1 [Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
[alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
[better behavior on smaller screen sizes]: https://twitter.com/squidfunk/status/1424740370596958214 [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
[Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
[Grouping other content]: ../../reference/content-tabs.md#grouping-other-content [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
[Embedded content]: ../../reference/content-tabs.md#embedded-content [Embedded content]: ../../reference/content-tabs.md#embedded-content
@ -644,8 +640,8 @@ See reference for usage:
[:octicons-tag-24: 1.0.0 ... present][Tasklist support] [:octicons-tag-24: 1.0.0 ... present][Tasklist support]
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown] The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
inspired [task lists][Spec], following the same syntactical conventions. Enable inspired [task lists][Tasklist specification], following the same syntactical
it via `mkdocs.yml`: conventions. Enable it via `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -659,7 +655,7 @@ The following configuration options are supported:
: :octicons-milestone-24: Default: `false` · This option toggles the rendering : :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons, style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore strongly recommended: and is therefore recommended:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -691,5 +687,5 @@ See reference for usage:
[Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[GitHub Flavored Markdown]: https://github.github.com/gfm/ [GitHub Flavored Markdown]: https://github.github.com/gfm/
[Tasklist #]: #tasklist [Tasklist #]: #tasklist
[Spec]: https://github.github.com/gfm/#task-list-items-extension- [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
[Using task lists]: ../../reference/lists.md#using-task-lists [Using task lists]: ../../reference/lists.md#using-task-lists

9
docs/setup/extensions/python-markdown.md
View File

@ -122,9 +122,8 @@ No configuration options are available. See reference for usage:
[:octicons-workflow-24: Extension][Footnotes] · [:octicons-workflow-24: Extension][Footnotes] ·
[:octicons-tag-24: 1.0.0 ... present][Footnotes support] [:octicons-tag-24: 1.0.0 ... present][Footnotes support]
The [Footnotes] extension allows to define footnotes inline with the content, The [Footnotes] extension allows to define inline footnotes, which are then
which are then rendered below all Markdown content of a document. Enable it rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
via `mkdocs.yml`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
@ -328,7 +327,7 @@ should be considered.
Superseded by [SuperFences]. This extension might still work, but the Superseded by [SuperFences]. This extension might still work, but the
[SuperFences] extension is superior in many ways, as it allows for arbitrary [SuperFences] extension is superior in many ways, as it allows for arbitrary
nesting, and therefore strongly recommended. nesting, and is therefore recommended.
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/ [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
[Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
@ -345,5 +344,5 @@ essential extensions like [SuperFences] and [InlineHilite].
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/ [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
[CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/

28
docs/setup/setting-up-navigation.md
View File

@ -82,11 +82,11 @@ theme:
- navigation.tabs - navigation.tabs
``` ```
=== "With tabs" === ":octicons-check-circle-fill-16: Enabled"
[![With tabs][8]][8] [![With tabs][8]][8]
=== "Without tabs" === ":octicons-skip-16: Disabled"
[![Without tabs][9]][9] [![Without tabs][9]][9]
@ -111,11 +111,11 @@ theme:
- navigation.tabs.sticky - navigation.tabs.sticky
``` ```
=== "With sticky tabs" === ":octicons-check-circle-fill-16: Enabled"
[![With sticky tabs][11]][11] [![With sticky tabs][11]][11]
=== "Without sticky tabs" === ":octicons-skip-16: Disabled"
[![Without sticky tabs][12]][12] [![Without sticky tabs][12]][12]
@ -138,11 +138,11 @@ theme:
- navigation.sections - navigation.sections
``` ```
=== "With sections" === ":octicons-check-circle-fill-16: Enabled"
[![With sections][14]][14] [![With sections][14]][14]
=== "Without sections" === ":octicons-skip-16: Disabled"
[![Without sections][9]][9] [![Without sections][9]][9]
@ -168,11 +168,11 @@ theme:
- navigation.expand - navigation.expand
``` ```
=== "With expansion" === ":octicons-check-circle-fill-16: Enabled"
[![With expansion][15]][15] [![With expansion][15]][15]
=== "Without expansion" === ":octicons-skip-16: Disabled"
[![Without expansion][9]][9] [![Without expansion][9]][9]
@ -194,11 +194,11 @@ theme:
- navigation.indexes - navigation.indexes
``` ```
=== "With section index pages" === ":octicons-check-circle-fill-16: Enabled"
[![With expansion][17]][17] [![With expansion][17]][17]
=== "Without section index pages" === ":octicons-skip-16: Disabled"
[![Without expansion][18]][18] [![Without expansion][18]][18]
@ -297,7 +297,7 @@ customize its appearance:
slugify: !!python/name:pymdownx.slugs.uslugify_cased slugify: !!python/name:pymdownx.slugs.uslugify_cased
``` ```
`toc_depth`{ #toc_depth } `toc_depth`{ #toc-depth }
: :octicons-milestone-24: Default: `6` – Define the range of levels to be : :octicons-milestone-24: Default: `6` – Define the range of levels to be
included in the table of contents. This may be useful for project included in the table of contents. This may be useful for project
@ -344,11 +344,11 @@ theme:
- toc.integrate - toc.integrate
``` ```
=== "Integrate table of contents" === ":octicons-check-circle-fill-16: Enabled"
[![Integrate table of contents][27]][27] [![Integrate table of contents][27]][27]
=== "Separate table of contents" === ":octicons-skip-16: Disabled"
[![Separate table of contents][8]][8] [![Separate table of contents][8]][8]
@ -459,7 +459,7 @@ is a reasonable default, as longer lines tend to be harder to read, it may be
desirable to increase the overall width of the content area, or even make it desirable to increase the overall width of the content area, or even make it
stretch to the entire available space. stretch to the entire available space.
This can easily be achieved with an [additional stylesheet][36] and a few lines This can easily be achieved with an [additional style sheet][36] and a few lines
of CSS: of CSS:
=== "Increase width" === "Increase width"

22
docs/setup/setting-up-site-analytics.md
View File

@ -51,11 +51,11 @@ Besides basic page views, _site search_ can also be tracked to understand better
how people use your documentation and what they expect to find. To enable how people use your documentation and what they expect to find. To enable
search tracking: search tracking:
1. Go to your Google Analytics __admin settings__ 1. Go to your Google Analytics __admin settings__
2. Select the property for the respective tracking code 2. Select the property for the respective tracking code
3. Go to the __view settings__ tab. 3. Go to the __view settings__ tab.
4. Scroll down and enable __site search settings__ 4. Scroll down and enable __site search settings__
5. Set the __query parameter__ to `q`. 5. Set the __query parameter__ to `q`.
_Site search tracking is not supported with Google Analytics 4 due to the much _Site search tracking is not supported with Google Analytics 4 due to the much
more complicated manual setup. If you want to set up site search tracking more complicated manual setup. If you want to set up site search tracking
@ -85,8 +85,8 @@ extra:
make our documentation better. make our documentation better.
``` ```
1. You can add arbitrary HTML tags in the `description`, e.g. to link to your 1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
terms of service or other parts of the site. terms of service or other parts of the site.
Note that both, `title` and `description`, are required. If Google Analytics was Note that both, `title` and `description`, are required. If Google Analytics was
configured via `mkdocs.yml`, the cookie consent will automatically include a configured via `mkdocs.yml`, the cookie consent will automatically include a
@ -153,10 +153,10 @@ extra:
key: value # (2) key: value # (2)
``` ```
1. Of course, you can change the name to the partial to anything you like. 1. Of course, you can change the name to the partial to anything you like.
2. You can add arbitrary `key` and `value` combinations to configure your custom 2. You can add arbitrary `key` and `value` combinations to configure your custom
integration. This is especially useful if you're sharing the custom integration. This is especially useful if you're sharing the custom
integration across multiple repositories. integration across multiple repositories.
[8]: ../customization.md#extending-the-theme [8]: ../customization.md#extending-the-theme
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics [9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics

22
docs/setup/setting-up-site-search.md
View File

@ -400,19 +400,19 @@ export function defaultTransform(query: string): string {
} }
``` ```
1. Search for terms in quotation marks and prepend a `+` modifier to denote 1. Search for terms in quotation marks and prepend a `+` modifier to denote
that the resulting document must contain all terms, converting the query that the resulting document must contain all terms, converting the query
to an `AND` query (as opposed to the default `OR` behavior). While users 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. 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 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. 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 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 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 character or are at the end of the query string. Furthermore, filter
unmatched quotation marks. unmatched quotation marks.
3. Trim excess whitespace from left and right. 3. Trim excess whitespace from left and right.
If you want to switch to the default behavior of the `mkdocs` and `readthedocs` If you want to switch to the default behavior of the `mkdocs` and `readthedocs`
themes, both of which don't transform the query prior to submission, or themes, both of which don't transform the query prior to submission, or

12
docs/setup/setting-up-social-cards.md
View File

@ -55,7 +55,7 @@ This is a built-in plugin, which means that no third-party plugin needs to be
installed, as Material for MkDocs already bundles it. The following options installed, as Material for MkDocs already bundles it. The following options
are available: are available:
`cards_color`{ #cards_color } :material-new-box: `cards_color`{ #cards-color } :material-new-box:
: :octicons-milestone-24: Default: _automatically set based on [primary : :octicons-milestone-24: Default: _automatically set based on [primary
color][8]_ – This option specifies which colors to use for the background color][8]_ – This option specifies which colors to use for the background
@ -73,7 +73,7 @@ are available:
(e.g. `#0FF1CE`, must be enclosed in quotes) or CSS color keywords (e.g. (e.g. `#0FF1CE`, must be enclosed in quotes) or CSS color keywords (e.g.
`red`, `green`, etc.). `red`, `green`, etc.).
`cards_directory`{ #cards_directory } `cards_directory`{ #cards-directory }
: :octicons-milestone-24: Default: `assets/images/social` – This option : :octicons-milestone-24: Default: `assets/images/social` – This option
specifies where the generated social card images will be written to. It specifies where the generated social card images will be written to. It
@ -100,10 +100,10 @@ is displayed on the social card. The font files and generated cards are both
written to the `.cache` directory, which is used in subsequent builds to detect written to the `.cache` directory, which is used in subsequent builds to detect
whether the social cards need to be regenerated. You might want to: whether the social cards need to be regenerated. You might want to:
1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`. 1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
2. When building your site for publishing, use a build cache to save the 2. When building your site for publishing, use a build cache to save the
`.cache` directory in between builds. Taking the example from the `.cache` directory in between builds. Taking the example from the
[publishing guide][10], add the following lines: [publishing guide][10], add the following lines:
``` yaml hl_lines="15-18" ``` yaml hl_lines="15-18"
name: ci name: ci

2
docs/setup/setting-up-tags.md
View File

@ -31,7 +31,7 @@ Note that no third-party plugin[^1] needs to be installed, as Material for
MkDocs provides its own implementation to allow for a meaningful integration. MkDocs provides its own implementation to allow for a meaningful integration.
The following options are available: The following options are available:
`tags_file`{ #tags_file } `tags_file`{ #tags-file }
: :octicons-milestone-24: Default: _none_ – This option specifies which file : :octicons-milestone-24: Default: _none_ – This option specifies which file
should be used to render the tags index. See the section on [adding a tags should be used to render the tags index. See the section on [adding a tags

10
docs/setup/setting-up-versioning.md
View File

@ -87,11 +87,11 @@ you can [define the `outdated` block][9]:
{% endblock %} {% endblock %}
``` ```
1. Given this value for the `href` attribute, the link will always redirect to 1. Given this value for the `href` attribute, the link will always redirect to
the root of your site, which will then redirect to the latest version. This the root of your site, which will then redirect to the latest version. This
ensures that older versions of your site do not depend on a specific alias, ensures that older versions of your site do not depend on a specific alias,
e.g. `latest`, to allow for changing the alias later on without breaking e.g. `latest`, to allow for changing the alias later on without breaking
earlier versions. earlier versions.
This will render a version warning above the header: This will render a version warning above the header:

2
mkdocs.yml
View File

@ -51,7 +51,7 @@ theme:
language: en language: en
features: features:
- content.code.annotate - content.code.annotate
- content.tabs.link # - content.tabs.link
# - header.autohide # - header.autohide
# - navigation.expand # - navigation.expand
- navigation.indexes - navigation.indexes