mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Updated documentation
This commit is contained in:
squidfunk
parent
02b009dcaf
commit
b6cd73e083
@ -39,7 +39,7 @@ extra_css:
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ template: overrides/main.html
|
||||
|
||||
# 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
|
||||
matters, Material for MkDocs uses a combination of Markdown extensions to
|
||||
enable site-wide glossaries.
|
||||
@ -69,7 +69,7 @@ all abbreviations in a dedicated file[^1], and embedding it with the
|
||||
|
||||
_Example_:
|
||||
|
||||
=== ":octicons-file-code-16: docs/page.md"
|
||||
=== ":octicons-file-code-16: docs/example.md"
|
||||
|
||||
```` markdown
|
||||
The HTML specification is maintained by the W3C.
|
||||
|
||||
@ -404,37 +404,9 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
|
||||
|
||||
### 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
|
||||
`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder
|
||||
and add the following CSS to an [additional stylesheet]:
|
||||
|
||||
``` 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].
|
||||
`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
|
||||
and add the following CSS to an [additional style sheet]:
|
||||
|
||||
<style>
|
||||
:root {
|
||||
@ -459,13 +431,45 @@ colors. [You can even add animations][Custom animations].
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
!!! pied-piper "Pied Piper"
|
||||
=== ":octicons-file-code-16: docs/example.md"
|
||||
|
||||
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.
|
||||
```
|
||||
``` markdown
|
||||
!!! pied-piper "Pied Piper"
|
||||
|
||||
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_:
|
||||
|
||||
@ -475,7 +479,5 @@ _Result_:
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
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 animations]: icons-emojis.md#with-animations
|
||||
[additional stylesheet]: ../customization.md#additional-css
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
[additional style sheet]: ../customization.md#additional-css
|
||||
|
||||
@ -30,38 +30,38 @@ See additional configuration options:
|
||||
### Adding buttons
|
||||
|
||||
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.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[Don't click me](#){ .md-button }
|
||||
[Subscribe to our newsletter](#){ .md-button }
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
[Don't click me][Demo]{ .md-button }
|
||||
[Subscribe to our newsletter][Demo]{ .md-button }
|
||||
|
||||
[primary color]: ../setup/changing-the-colors.md#primary-color
|
||||
[accent color]: ../setup/changing-the-colors.md#accent-color
|
||||
[Demo]: javascript:alert$.next("Hi!")
|
||||
[Demo]: javascript:alert$.next("Demo")
|
||||
|
||||
### Adding primary buttons
|
||||
|
||||
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
|
||||
`#!css .md-button--primary` CSS class selectors.
|
||||
of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
|
||||
CSS class selectors.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
[Don't click me](#){ .md-button .md-button--primary }
|
||||
[Subscribe to our newsletter](#){ .md-button .md-button--primary }
|
||||
```
|
||||
|
||||
_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
|
||||
|
||||
|
||||
@ -63,7 +63,7 @@ theme:
|
||||
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
|
||||
code block by using a slightly different syntax based on the
|
||||
[Attribute List] extension:
|
||||
[Attribute Lists] extension:
|
||||
|
||||
```` yaml
|
||||
``` { .yaml .annotate }
|
||||
@ -75,7 +75,7 @@ theme:
|
||||
prefixed by a `.`.
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[Attribute List]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
|
||||
## Usage
|
||||
|
||||
@ -270,11 +270,8 @@ last 4 years
|
||||
|
||||
### 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]
|
||||
[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]:
|
||||
|
||||
- :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
|
||||
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
|
||||
:root > * {
|
||||
=== ":octicons-file-code-16: docs/stylesheets/colors.css"
|
||||
|
||||
``` 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
|
||||
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
|
||||
.highlight .sb {
|
||||
=== ":octicons-file-code-16: docs/stylesheets/colors.css"
|
||||
|
||||
``` css
|
||||
.highlight .sb {
|
||||
color: #0FF1CE;
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
[Source]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
|
||||
=== ":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
|
||||
[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
|
||||
|
||||
@ -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
|
||||
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
|
||||
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[With linking]: ../assets/screenshots/content-tabs-link.png
|
||||
[Without linking]: ../assets/screenshots/content-tabs.png
|
||||
[linking enabled]: ../assets/screenshots/content-tabs-link.png
|
||||
[linking disabled]: ../assets/screenshots/content-tabs.png
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -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
|
||||
loading] via [additional JavaScript]:
|
||||
|
||||
=== ":octicons-file-code-16: docs/javascripts/tables.js"
|
||||
=== ":octicons-file-code-16: docs/javascripts/tablesort.js"
|
||||
|
||||
``` js
|
||||
document$.subscribe(function() {
|
||||
@ -148,7 +148,7 @@ loading] via [additional JavaScript]:
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- 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
|
||||
|
||||
@ -34,8 +34,8 @@ No further configuration is necessary. Advantages over a custom integration:
|
||||
|
||||
- [x] Works with [instant loading] without any additional effort
|
||||
- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
|
||||
- [x] Fonts and colors can be customized with [additional stylesheets]
|
||||
- [x] Support for both, light and dark color schemes
|
||||
- [x] Fonts and colors can be customized with [additional style sheets]
|
||||
- [x] Support for both, light and dark color schemes – _try it on this page!_
|
||||
|
||||
[^1]:
|
||||
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
|
||||
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[additional stylesheets]: ../customization.md#additional-css
|
||||
[additional style sheets]: ../customization.md#additional-css
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -4,16 +4,16 @@ template: overrides/main.html
|
||||
|
||||
# Footnotes
|
||||
|
||||
Footnotes are a great way to add references to supplemental or additional
|
||||
information to a specific word, phrase or sentence without interrupting the
|
||||
flow of a document. Material for MkDocs provides the ability to define and
|
||||
render footnotes.
|
||||
Footnotes are a great way to add supplemental or additional information to a
|
||||
specific word, phrase or sentence without interrupting the flow of a document.
|
||||
Material for MkDocs provides the ability to define, reference and render
|
||||
footnotes.
|
||||
|
||||
## Configuration
|
||||
|
||||
This configuration adds the ability to define footnotes inline with the content,
|
||||
which are then rendered below all Markdown content of a document. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
This configuration adds the ability to define inline footnotes, which are then
|
||||
rendered below all Markdown content of a document. Add the following lines to
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
|
||||
@ -13,8 +13,8 @@ for a document.
|
||||
|
||||
## Configuration
|
||||
|
||||
This configuration enables support for keyboard keys, highlighting changes
|
||||
to documents, highlighting text and defining sub- and superscript. Add the
|
||||
This configuration enables support for keyboard keys, tracking changes in
|
||||
documents, defining sub- and superscript and highlighting text. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
@ -26,6 +26,8 @@ markdown_extensions:
|
||||
- pymdownx.tilde
|
||||
```
|
||||
|
||||
See additional configuration options:
|
||||
|
||||
- [Critic]
|
||||
- [Caret, Mark & Tilde]
|
||||
- [Keys]
|
||||
@ -77,8 +79,8 @@ Text can be <del class="critic">deleted</del> and replacement text
|
||||
### Highlighting text
|
||||
|
||||
When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
|
||||
syntax, which is more convenient that directly using the corresponding `mark`,
|
||||
`ins` and `del` HTML tags.
|
||||
syntax, which is more convenient that directly using the corresponding
|
||||
[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -94,11 +96,15 @@ _Result_:
|
||||
- ^^This was inserted^^
|
||||
- ~~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
|
||||
|
||||
When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
|
||||
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_:
|
||||
|
||||
@ -112,6 +118,9 @@ _Result_:
|
||||
- H~2~0
|
||||
- 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
|
||||
|
||||
When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
@ -128,4 +137,4 @@ _Result_:
|
||||
|
||||
++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
|
||||
|
||||
@ -59,7 +59,7 @@ See additional configuration options:
|
||||
[Octicons]: https://octicons.github.com/
|
||||
[additional icons]: ../setup/changing-the-logo-and-icons.md#additional-icons
|
||||
[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
|
||||
|
||||
@ -86,46 +86,33 @@ _Result_:
|
||||
|
||||
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
|
||||
[`.icons`][1] directory, and replacing `/` with `-`:
|
||||
[`.icons`][custom icons] directory, and replacing `/` with `-`:
|
||||
|
||||
_Example_:
|
||||
|
||||
```
|
||||
- :material-account-circle: – `.icons/material/account-circle.svg`
|
||||
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
|
||||
- :octicons-repo-push-16: – `.icons/octicons/repo-push-16.svg`
|
||||
- :material-account-circle: – `material/account-circle.svg`
|
||||
- :fontawesome-regular-laugh-wink: – `fontawesome/regular/laugh-wink.svg`
|
||||
- :octicons-repo-push-16: – `octicons/repo-push-16.svg`
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
- :material-account-circle: – [`.icons/material/account-circle.svg`][14]
|
||||
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
|
||||
- :octicons-repo-push-16: – [`.icons/octicons/repo-push-16.svg`][16]
|
||||
- :material-account-circle: – [`material/account-circle.svg`][icon Material]
|
||||
- :fontawesome-regular-laugh-wink: – [`fontawesome/regular/laugh-wink.svg`][icon FontAwesome]
|
||||
- :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
|
||||
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
|
||||
[16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/repo-push-16.svg
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
[icon Material]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.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
|
||||
|
||||
When the [Attribute List][17] extension is enabled, custom CSS classes and
|
||||
attributes can be added to icons by suffixing the icon with a special syntax.
|
||||
While HTML and CSS allow to use [inline styles][18], it's always best to add
|
||||
an [additional stylesheet][19] and put styles into dedicated CSS classes:
|
||||
|
||||
``` css
|
||||
.medium {
|
||||
color: #00AB6C;
|
||||
}
|
||||
.twitter {
|
||||
color: #1DA1F2;
|
||||
}
|
||||
.facebook {
|
||||
color: #4267B2;
|
||||
}
|
||||
```
|
||||
|
||||
Then, simply add the CSS class to the icon.
|
||||
When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
|
||||
suffixing the icon with a special syntax. While HTML allows to use
|
||||
[inline styles], it's always recommended to add an [additional style sheet] and
|
||||
move declarations into dedicated CSS classes.
|
||||
|
||||
<style>
|
||||
.medium {
|
||||
@ -141,11 +128,34 @@ Then, simply add the CSS class to the icon.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
- :fontawesome-brands-medium:{ .medium } – Medium
|
||||
- :fontawesome-brands-twitter:{ .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{ .facebook } – Facebook
|
||||
```
|
||||
=== ":octicons-file-code-16: docs/example.md"
|
||||
|
||||
``` markdown
|
||||
- :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_:
|
||||
|
||||
@ -153,52 +163,61 @@ _Result_:
|
||||
- :fontawesome-brands-twitter:{ .twitter } – Twitter
|
||||
- :fontawesome-brands-facebook:{ .facebook } – Facebook
|
||||
|
||||
[17]: #attribute-list
|
||||
[18]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
|
||||
[19]: ../customization.md#additional-css
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
[inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
|
||||
[additional style sheet]: ../customization.md#additional-css
|
||||
|
||||
#### with animations
|
||||
|
||||
Similar to adding [colors][20], it's just as easy to add [CSS animations][21] to
|
||||
icons by using an [additional stylesheet][6], defining a `#!css @keyframes` rule
|
||||
and adding the dedicated CSS class to the icon:
|
||||
Similar to adding [colors], it's just as easy to add [animations] to icons by
|
||||
using an [additional style sheet], defining a `@keyframes` rule and adding a
|
||||
dedicated CSS class to the icon.
|
||||
|
||||
``` css
|
||||
@keyframes heart {
|
||||
_Example_:
|
||||
|
||||
=== ":octicons-file-code-16: docs/example.md"
|
||||
|
||||
``` 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 {
|
||||
}
|
||||
.heart {
|
||||
animation: heart 1000ms infinite;
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
Then, simply add the CSS class to the icon.
|
||||
=== ":octicons-file-code-16: mkdocs.yml"
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
:octicons-heart-fill-24:{ .heart }
|
||||
```
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/icons.css
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
:octicons-heart-fill-24:{ .mdx-heart }
|
||||
|
||||
[20]: #with-colors
|
||||
[21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
|
||||
[colors]: #with-colors
|
||||
[animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
|
||||
|
||||
## Customization
|
||||
|
||||
### Using icons in templates
|
||||
|
||||
When you're [extending the theme][22] with partials or blocks, you can simply
|
||||
reference any icon that's [bundled with the theme][1] with Jinja's
|
||||
[`include`][23] function and wrap it with the `twemoji` class:
|
||||
When you're [extending the theme] with partials or blocks, you can simply
|
||||
reference any icon that's [bundled with the theme][icon search] with Jinja's
|
||||
[`include`][include] function and wrap it with the `.twemoji` CSS class:
|
||||
|
||||
``` html
|
||||
<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.
|
||||
|
||||
[22]: ../customization.md#extending-the-theme
|
||||
[23]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
|
||||
[extending the theme]: ../customization.md#extending-the-theme
|
||||
[include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
|
||||
|
||||
@ -6,32 +6,36 @@ template: overrides/main.html
|
||||
|
||||
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
|
||||
images more comfortable by providing styles for alignment and image captions.
|
||||
|
||||
[1]: https://www.markdownguide.org/basic-syntax/#images-1
|
||||
images more comfortable, providing styles for image alignment and image
|
||||
captions.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Attribute List
|
||||
|
||||
The [Attribute List][2] extension, which is part of the standard Markdown
|
||||
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
|
||||
and can be enabled via `mkdocs.yml`
|
||||
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
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- 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
|
||||
|
||||
### Image alignment
|
||||
|
||||
When the [Attribute List][3] extension is enabled, images can be aligned by
|
||||
adding the respective alignment directions via the `align` attribute, i.e.
|
||||
`align=left` or `align=right`
|
||||
When [Attribute Lists] is enabled, images can be aligned by adding the
|
||||
respective alignment directions via the `align` attribute, i.e. `align=left` or
|
||||
`align=right`:
|
||||
|
||||
=== "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
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
_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._
|
||||
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.
|
||||
|
||||
[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
|
||||
|
||||
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_:
|
||||
|
||||
@ -98,10 +118,9 @@ _Result_:
|
||||
|
||||
### Image lazy-loading
|
||||
|
||||
Modern browsers provide [native support for lazy-loading images][4] through the
|
||||
`loading` attribute, which degrades to eager-loading in browsers without
|
||||
support. As with [image alignment][5], if the [Attribute List][3] extension is
|
||||
enabled, images can be lazy-loaded by adding `loading=lazy`.
|
||||
Modern browsers provide [native support for lazy-loading images][lazy-loading]
|
||||
through the `loading=lazy` directive, which degrades to eager-loading in
|
||||
browsers without support
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -113,5 +132,4 @@ _Result_:
|
||||
|
||||
{ loading=lazy width=300 }
|
||||
|
||||
[4]: https://caniuse.com/#feat=loading-lazy-attr
|
||||
[5]: #image-alignment
|
||||
[lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
|
||||
|
||||
@ -11,64 +11,31 @@ are supported through extensions.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Definition List
|
||||
|
||||
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
|
||||
|
||||
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`:
|
||||
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
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- def_list
|
||||
```
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
|
||||
[2]: https://python-markdown.github.io/extensions/definition_lists/
|
||||
|
||||
### Tasklist
|
||||
|
||||
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
|
||||
|
||||
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 }
|
||||
See additional configuration options:
|
||||
|
||||
: :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:
|
||||
- [Definition Lists]
|
||||
- [Tasklist]
|
||||
|
||||
``` 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/
|
||||
[Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists
|
||||
[Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist
|
||||
|
||||
## Usage
|
||||
|
||||
### Using unordered lists
|
||||
|
||||
An unordered list can be written by prefixing a line with a `-`, `*` or `+`
|
||||
list marker, all of which can be used interchangeably. Furthermore, all flavors
|
||||
Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
|
||||
marker, all of which can be used interchangeably. Furthermore, all flavors
|
||||
of lists can be nested inside each other.
|
||||
|
||||
_Example_:
|
||||
@ -95,7 +62,7 @@ _Result_:
|
||||
|
||||
### 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
|
||||
be re-numbered when rendered.
|
||||
|
||||
@ -137,18 +104,19 @@ _Result_:
|
||||
|
||||
### Using definition lists
|
||||
|
||||
[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g.
|
||||
the parameters of functions or modules, as used within this documentation to
|
||||
describe extension or plugin parameters.
|
||||
When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
|
||||
parameters of functions or modules, can be enumerated with a simple syntax.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
`Lorem ipsum dolor sit amet`
|
||||
|
||||
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
|
||||
tellus non sem sollicitudin, quis rutrum leo facilisis.
|
||||
|
||||
`Cras arcu libero`
|
||||
|
||||
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
|
||||
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
|
||||
|
||||
@ -160,10 +128,12 @@ _Example_:
|
||||
_Result_:
|
||||
|
||||
`Lorem ipsum dolor sit amet`
|
||||
|
||||
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
|
||||
tellus non sem sollicitudin, quis rutrum leo facilisis.
|
||||
|
||||
`Cras arcu libero`
|
||||
|
||||
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
|
||||
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
|
||||
|
||||
@ -171,13 +141,11 @@ _Result_:
|
||||
Nam vulputate tincidunt fringilla.
|
||||
Nullam dignissim ultrices urna non auctor.
|
||||
|
||||
[6]: #definition-list
|
||||
|
||||
### Using task lists
|
||||
|
||||
When the [Tasklist][7] extension is enabled, unordered list items can be
|
||||
prefixed with `[ ]` to render an unchecked or `[x]` to render a checked
|
||||
checkbox.
|
||||
When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
|
||||
render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
|
||||
for the definition of task lists.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -198,5 +166,3 @@ _Result_:
|
||||
* [x] In scelerisque nibh non dolor mollis congue sed et metus
|
||||
* [ ] Praesent sed risus massa
|
||||
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
|
||||
|
||||
[7]: #tasklist
|
||||
|
||||
@ -4,37 +4,23 @@ template: overrides/main.html
|
||||
|
||||
# MathJax
|
||||
|
||||
[MathJax][1] is a beautiful and accessible way to display _mathematical content_
|
||||
in the browser, allows for writing formulas in different notations, including
|
||||
[LaTeX][2], [MathML][3] and [AsciiMath][4], and can be easily integrated with
|
||||
[MathJax] is a beautiful and accessible way to display mathematical content
|
||||
in the browser, adds support for mathematical typesetting in different notations
|
||||
(e.g. [LaTeX], [MathML], [AsciiMath]), and can be easily integrated with
|
||||
Material for MkDocs.
|
||||
|
||||
[1]: https://www.mathjax.org/
|
||||
[2]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
|
||||
[3]: https://en.wikipedia.org/wiki/MathML
|
||||
[4]: http://asciimath.org/
|
||||
[MathJax]: https://www.mathjax.org/
|
||||
[LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
|
||||
[MathML]: https://en.wikipedia.org/wiki/MathML
|
||||
[AsciiMath]: http://asciimath.org/
|
||||
|
||||
## 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]
|
||||
|
||||
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"
|
||||
=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
|
||||
|
||||
``` js
|
||||
window.MathJax = {
|
||||
@ -50,31 +36,32 @@ JavaScript][8]:
|
||||
}
|
||||
};
|
||||
|
||||
document$.subscribe(() => {
|
||||
document$.subscribe(() => { // (1)
|
||||
MathJax.typesetPromise()
|
||||
})
|
||||
```
|
||||
|
||||
=== "mkdocs.yml"
|
||||
1. This integrates MathJax with [instant loading].
|
||||
|
||||
=== ":octicons-file-code-16: mkdocs.yml"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.arithmatex:
|
||||
generic: true
|
||||
|
||||
extra_javascript:
|
||||
- javascripts/config.js
|
||||
- javascripts/mathjax.js
|
||||
- https://polyfill.io/v3/polyfill.min.js?features=es6
|
||||
- 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
|
||||
might not provide native support. See the [official documentation][6] for more
|
||||
information._
|
||||
See additional configuration options:
|
||||
|
||||
!!! tip "Using MathJax with [instant loading][9]"
|
||||
- [Arithmatex]
|
||||
|
||||
There's no additional effort necessary to integrate _MathJax 3_ with
|
||||
[instant loading][9] – it's expected to work straight away. However, a
|
||||
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_.
|
||||
[Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
|
||||
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
|
||||
<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>
|
||||
@ -93,12 +80,6 @@ information._
|
||||
};
|
||||
</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
|
||||
|
||||
### Using block syntax
|
||||
|
||||
@ -121,7 +121,7 @@ plugins:
|
||||
|
||||
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
|
||||
if the environment variable exists. This makes it possible to disable
|
||||
@ -174,7 +174,7 @@ The following options are supported:
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
`enable_creation_date`{ #enable_creation_date }
|
||||
`enable_creation_date`{ #enable-creation-date }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` – Enables the display of the
|
||||
_created at_ date of the file associated with the page next to the
|
||||
|
||||
@ -252,7 +252,7 @@ default color palette.
|
||||
|
||||
Material for MkDocs implements colors using [CSS variables][12] (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][13] and
|
||||
use your brand-specific colors), you can add an [additional style sheet][13] and
|
||||
tweak the values of the CSS variables.
|
||||
|
||||
Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
|
||||
|
||||
@ -77,7 +77,7 @@ theme:
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
|
||||
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:
|
||||
|
||||
``` css
|
||||
|
||||
@ -5,7 +5,7 @@ template: overrides/main.html
|
||||
# Python Markdown Extensions
|
||||
|
||||
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
|
||||
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
|
||||
of [additional JavaScript]:
|
||||
|
||||
=== ":octicons-file-code-16: docs/javascripts/config.js"
|
||||
=== ":octicons-file-code-16: docs/javascripts/mathjax.js"
|
||||
|
||||
``` js
|
||||
window.MathJax = {
|
||||
@ -62,7 +62,7 @@ of [additional JavaScript]:
|
||||
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- javascripts/config.js
|
||||
- javascripts/mathjax.js
|
||||
- https://polyfill.io/v3/polyfill.min.js?features=es6
|
||||
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
|
||||
```
|
||||
@ -237,7 +237,7 @@ markdown_extensions:
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`emoji_index`{ #emoji_index }
|
||||
`emoji_index`{ #emoji-index }
|
||||
|
||||
: :octicons-milestone-24: Default: `emojione` – This option defines which set
|
||||
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_generator`{ #emoji_generator }
|
||||
`emoji_generator`{ #emoji-generator }
|
||||
|
||||
: :octicons-milestone-24: Default: `to_png` – This option defines how the
|
||||
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
|
||||
```
|
||||
|
||||
`options.custom_icons`{ #custom_icons }
|
||||
`options.custom_icons`{ #custom-icons }
|
||||
|
||||
: :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].
|
||||
|
||||
``` yaml
|
||||
@ -315,17 +315,13 @@ markdown_extensions:
|
||||
perform syntax highlighting on code blocks, not the other way round, which
|
||||
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:
|
||||
|
||||
`use_pygments`{ #use-pygments }
|
||||
|
||||
: :octicons-milestone-24: Default: `true` – This option allows to control
|
||||
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"
|
||||
|
||||
@ -348,7 +344,7 @@ The following configuration options are supported:
|
||||
integrated with some [additional JavaScript] and [CSS][additional CSS]
|
||||
in `mkdocs.yml`:
|
||||
|
||||
=== ":octicons-file-code-16: docs/javascripts/config.js"
|
||||
=== ":octicons-file-code-16: docs/javascripts/highlight.js"
|
||||
|
||||
``` js
|
||||
document$.subscribe(() => {
|
||||
@ -361,7 +357,7 @@ The following configuration options are supported:
|
||||
``` yaml
|
||||
extra_javascript:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
|
||||
- javascripts/config.js
|
||||
- javascripts/highlight.js
|
||||
extra_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:
|
||||
|
||||
`custom_fences`{ #custom_fences }
|
||||
`custom_fences`{ #custom-fences }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ – This option allows to define a
|
||||
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:
|
||||
|
||||
`alternate_style`{ #alternate_style }
|
||||
`alternate_style`{ #alternate-style }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` · [:octicons-tag-24: 7.3.1]
|
||||
[Tabbed alternate support] – This option enables the [alternate style] of
|
||||
content tabs, which has [better behavior on smaller screen sizes], and thus
|
||||
is _strongly recommended_:
|
||||
content tabs, which has [better behavior on mobile viewports], and thus
|
||||
is strongly recommended:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -633,7 +629,7 @@ See reference for usage:
|
||||
[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
|
||||
[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 other content]: ../../reference/content-tabs.md#grouping-other-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]
|
||||
|
||||
The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
|
||||
inspired [task lists][Spec], following the same syntactical conventions. Enable
|
||||
it via `mkdocs.yml`:
|
||||
inspired [task lists][Tasklist specification], following the same syntactical
|
||||
conventions. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -659,7 +655,7 @@ The following configuration options are supported:
|
||||
|
||||
: :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:
|
||||
and is therefore recommended:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -691,5 +687,5 @@ See reference for usage:
|
||||
[Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[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
|
||||
|
||||
@ -122,9 +122,8 @@ No configuration options are available. See reference for usage:
|
||||
[:octicons-workflow-24: Extension][Footnotes] ·
|
||||
[:octicons-tag-24: 1.0.0 ... present][Footnotes support]
|
||||
|
||||
The [Footnotes] extension allows to define footnotes inline with the content,
|
||||
which are then rendered below all Markdown content of a document. Enable it
|
||||
via `mkdocs.yml`:
|
||||
The [Footnotes] extension allows to define inline footnotes, which are then
|
||||
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -328,7 +327,7 @@ should be considered.
|
||||
|
||||
Superseded by [SuperFences]. This extension might still work, but the
|
||||
[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 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 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/
|
||||
|
||||
@ -82,11 +82,11 @@ theme:
|
||||
- navigation.tabs
|
||||
```
|
||||
|
||||
=== "With tabs"
|
||||
=== ":octicons-check-circle-fill-16: Enabled"
|
||||
|
||||
[![With tabs][8]][8]
|
||||
|
||||
=== "Without tabs"
|
||||
=== ":octicons-skip-16: Disabled"
|
||||
|
||||
[![Without tabs][9]][9]
|
||||
|
||||
@ -111,11 +111,11 @@ theme:
|
||||
- navigation.tabs.sticky
|
||||
```
|
||||
|
||||
=== "With sticky tabs"
|
||||
=== ":octicons-check-circle-fill-16: Enabled"
|
||||
|
||||
[![With sticky tabs][11]][11]
|
||||
|
||||
=== "Without sticky tabs"
|
||||
=== ":octicons-skip-16: Disabled"
|
||||
|
||||
[![Without sticky tabs][12]][12]
|
||||
|
||||
@ -138,11 +138,11 @@ theme:
|
||||
- navigation.sections
|
||||
```
|
||||
|
||||
=== "With sections"
|
||||
=== ":octicons-check-circle-fill-16: Enabled"
|
||||
|
||||
[![With sections][14]][14]
|
||||
|
||||
=== "Without sections"
|
||||
=== ":octicons-skip-16: Disabled"
|
||||
|
||||
[![Without sections][9]][9]
|
||||
|
||||
@ -168,11 +168,11 @@ theme:
|
||||
- navigation.expand
|
||||
```
|
||||
|
||||
=== "With expansion"
|
||||
=== ":octicons-check-circle-fill-16: Enabled"
|
||||
|
||||
[![With expansion][15]][15]
|
||||
|
||||
=== "Without expansion"
|
||||
=== ":octicons-skip-16: Disabled"
|
||||
|
||||
[![Without expansion][9]][9]
|
||||
|
||||
@ -194,11 +194,11 @@ theme:
|
||||
- navigation.indexes
|
||||
```
|
||||
|
||||
=== "With section index pages"
|
||||
=== ":octicons-check-circle-fill-16: Enabled"
|
||||
|
||||
[![With expansion][17]][17]
|
||||
|
||||
=== "Without section index pages"
|
||||
=== ":octicons-skip-16: Disabled"
|
||||
|
||||
[![Without expansion][18]][18]
|
||||
|
||||
@ -297,7 +297,7 @@ customize its appearance:
|
||||
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
|
||||
included in the table of contents. This may be useful for project
|
||||
@ -344,11 +344,11 @@ theme:
|
||||
- toc.integrate
|
||||
```
|
||||
|
||||
=== "Integrate table of contents"
|
||||
=== ":octicons-check-circle-fill-16: Enabled"
|
||||
|
||||
[![Integrate table of contents][27]][27]
|
||||
|
||||
=== "Separate table of contents"
|
||||
=== ":octicons-skip-16: Disabled"
|
||||
|
||||
[![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
|
||||
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:
|
||||
|
||||
=== "Increase width"
|
||||
|
||||
@ -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
|
||||
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
|
||||
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.
|
||||
`red`, `green`, etc.).
|
||||
|
||||
`cards_directory`{ #cards_directory }
|
||||
`cards_directory`{ #cards-directory }
|
||||
|
||||
: :octicons-milestone-24: Default: `assets/images/social` – This option
|
||||
specifies where the generated social card images will be written to. It
|
||||
|
||||
@ -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.
|
||||
The following options are available:
|
||||
|
||||
`tags_file`{ #tags_file }
|
||||
`tags_file`{ #tags-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
|
||||
|
||||
@ -51,7 +51,7 @@ theme:
|
||||
language: en
|
||||
features:
|
||||
- content.code.annotate
|
||||
- content.tabs.link
|
||||
# - content.tabs.link
|
||||
# - header.autohide
|
||||
# - navigation.expand
|
||||
- navigation.indexes
|
||||
|
||||
Loading…
Reference in New Issue
Block a user