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
b70342d918
commit
0436c9937b
@ -14,7 +14,7 @@ __The latest Insiders release brings three new simple ways to exclude
|
||||
dedicated parts of a document from the search index, allowing for more
|
||||
fine-grained control.__
|
||||
|
||||
<aside class="mdx-author" markdown="1">
|
||||
<aside class="mdx-author" markdown>
|
||||
![@squidfunk][1]
|
||||
|
||||
<span>__Martin Donath__ · @squidfunk</span>
|
||||
|
||||
@ -14,7 +14,7 @@ __This is the story of how we managed to completely rebuild client-side search,
|
||||
delivering a significantly better user experience while making it faster and
|
||||
smaller at the same time.__
|
||||
|
||||
<aside class="mdx-author" markdown="1">
|
||||
<aside class="mdx-author" markdown>
|
||||
![@squidfunk][1]
|
||||
|
||||
<span>__Martin Donath__ · @squidfunk</span>
|
||||
@ -230,11 +230,11 @@ search previews appear not to include any occurrence of any of the search
|
||||
terms. This was due to the fact that search previews were [truncated after a
|
||||
maximum of 320 characters][15], as can be seen here:
|
||||
|
||||
<figure markdown="1">
|
||||
<figure markdown>
|
||||
|
||||
![Search previews][16]
|
||||
|
||||
<figcaption markdown="1">
|
||||
<figcaption markdown>
|
||||
|
||||
The first two results look like they're not relevant, as they don't seem to
|
||||
include the query string the user just searched for. Yet, they are.
|
||||
@ -578,7 +578,7 @@ itself, and one with a very massive corpus of Markdown files with more than
|
||||
800,000 words – a size most documentation projects will likely never
|
||||
reach:
|
||||
|
||||
<figure markdown="1">
|
||||
<figure markdown>
|
||||
|
||||
| | Before | Now | Relative |
|
||||
| ----------------------- | -------: | -------------: | -----------: |
|
||||
|
||||
@ -91,7 +91,7 @@ Material for MkDocs comes with many configuration options. The _setup_ section
|
||||
explains in great detail how to configure and customize colors, fonts, icons
|
||||
and much more:
|
||||
|
||||
<div class="mdx-columns" markdown="1">
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [Changing the colors][5]
|
||||
- [Changing the fonts][6]
|
||||
|
||||
@ -10,11 +10,11 @@ that _new features are first exclusively released to sponsors_ as part of
|
||||
__Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
|
||||
to [get access to Insiders][2].
|
||||
|
||||
<figure class="mdx-video" markdown="1">
|
||||
<figure class="mdx-video" markdown>
|
||||
<div class="mdx-video__inner">
|
||||
<iframe src="https://streamable.com/e/ihhxw0" allowfullscreen></iframe>
|
||||
</div>
|
||||
<figcaption markdown="1">
|
||||
<figcaption markdown>
|
||||
|
||||
The official documentation is built with Insiders
|
||||
[squidfunk.github.io/mkdocs-material][3]
|
||||
@ -100,7 +100,7 @@ You can cancel your sponsorship anytime.[^4]
|
||||
|
||||
<hr />
|
||||
|
||||
<div class="mdx-premium" markdown="1">
|
||||
<div class="mdx-premium" markdown>
|
||||
|
||||
**Special thanks** to our **premium sponsors**:
|
||||
|
||||
@ -135,7 +135,7 @@ You can cancel your sponsorship anytime.[^4]
|
||||
|
||||
The following features are currently exclusively available to sponsors:
|
||||
|
||||
<div class="mdx-columns" markdown="1">
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [x] [Brand new search plugin :material-new-box:][35]
|
||||
- [x] [Rich search previews :material-new-box:][36]
|
||||
|
||||
@ -11,8 +11,8 @@ enable site-wide glossaries.
|
||||
|
||||
## Configuration
|
||||
|
||||
This configuration enables abbreviations, and allows to build a simple
|
||||
project-wide glossary sourcing definitions from a central location. Add the
|
||||
This configuration enables abbreviations and allows to build a simple
|
||||
project-wide glossary, sourcing definitions from a central location. Add the
|
||||
following line to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
@ -57,8 +57,8 @@ The HTML specification is maintained by the W3C.
|
||||
|
||||
### Adding a glossary
|
||||
|
||||
The [Snippets] extension can be used to implement a simple glossary, by moving
|
||||
all abbreviations in a dedicated file[^1] and include it with the
|
||||
The [Snippets] extension can be used to implement a simple glossary by moving
|
||||
all abbreviations in a dedicated file[^1], and embedding it with the
|
||||
[`--8<--` notation][Snippets notation] at the end of each document.
|
||||
|
||||
[^1]:
|
||||
|
||||
@ -12,7 +12,7 @@ inclusion and nesting of arbitrary content.
|
||||
## Configuration
|
||||
|
||||
This configuration enables admonitions, allows to make them collapsible and to
|
||||
nest arbitrary content inside admonition bodies. Add the following lines to
|
||||
nest arbitrary content inside admonitions. Add the following lines to
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
@ -38,8 +38,19 @@ See additional configuration options:
|
||||
[:octicons-tag-24: insiders-2.4.0 ... present][Insiders]
|
||||
|
||||
Each of the supported admonition types has a distinct icon, which can be changed
|
||||
to any icon bundled with the theme. Just set the name of the admonition type to
|
||||
a valid icon in `mkdocs.yml`:
|
||||
to any icon bundled with the theme. Add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
icon:
|
||||
admonition:
|
||||
<type>: <icon> # (1)
|
||||
```
|
||||
|
||||
1. Set `<type`> to any of the [supported types] and `<icon>` to any valid icon
|
||||
shortcode, which you can find by using the [icon search].
|
||||
|
||||
??? example "Example: using alternative icon sets"
|
||||
|
||||
=== ":octicons-mark-github-16: Octicons"
|
||||
|
||||
@ -95,6 +106,8 @@ a valid icon in `mkdocs.yml`:
|
||||
[![FontAwesome]][FontAwesome]
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[supported types]: #supported-types
|
||||
[icon search]: icons-emojis.md#search
|
||||
[Octicons]: ../assets/screenshots/admonition-octicons.png
|
||||
[FontAwesome]: ../assets/screenshots/admonition-fontawesome.png
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ during runtime using a JavaScript syntax highlighter.
|
||||
|
||||
This configuration enables syntax highlighting on code blocks and inline code
|
||||
blocks, and allows to include source code directly from other files. Add the
|
||||
following lines to `mkdocs.yml`
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -46,7 +46,7 @@ See additional configuration options:
|
||||
|
||||
Code annotations offer a comfortable and friendly way to attach arbitrary
|
||||
content to specific sections of code blocks by adding numeric markers in block
|
||||
and inline comments in the language of the block. Add the following to
|
||||
and inline comments in the language of the code block. Add the following to
|
||||
`mkdocs.yml` to enable them globally:
|
||||
|
||||
``` yaml
|
||||
@ -58,7 +58,7 @@ theme:
|
||||
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
|
||||
text__, images, ... basically anything that can be expressed in Markdown.
|
||||
|
||||
??? info "Enabling code annotations only for specific code blocks"
|
||||
??? info "Enabling code annotations for a specific code block"
|
||||
|
||||
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
|
||||
@ -194,7 +194,7 @@ at `1`, regardless of the starting line number specified as part of
|
||||
|
||||
_Result_:
|
||||
|
||||
``` python hl_lines="2 3"
|
||||
``` python linenums="1" hl_lines="2 3"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
@ -218,7 +218,7 @@ at `1`, regardless of the starting line number specified as part of
|
||||
|
||||
_Result_:
|
||||
|
||||
``` python hl_lines="2-5"
|
||||
``` python linenums="1" hl_lines="2-5"
|
||||
def bubble_sort(items):
|
||||
for i in range(len(items)):
|
||||
for j in range(len(items) - 1 - i):
|
||||
@ -246,8 +246,9 @@ The `#!python range()` function is used to generate a sequence of numbers.
|
||||
|
||||
### Embedding external files
|
||||
|
||||
When [Snippets] is enabled, content from other files can be embedded, which is particularly useful to reference and embed the contents of source files
|
||||
directly in a document without copying.
|
||||
When [Snippets] is enabled, content from other files (including source files)
|
||||
can be embedded by using the [`--8<--` notation][Snippets notation] directly
|
||||
from within a code block:
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -263,6 +264,8 @@ _Result_:
|
||||
last 4 years
|
||||
```
|
||||
|
||||
[Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom syntax theme
|
||||
@ -303,9 +306,9 @@ a new color by using an [additional stylesheet]:
|
||||
}
|
||||
```
|
||||
|
||||
If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
|
||||
can lookup the specific class name in the [syntax theme definition], and
|
||||
override it as part of your additional stylesheet:
|
||||
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]:
|
||||
|
||||
``` css
|
||||
.highlight .sb {
|
||||
|
||||
@ -11,9 +11,9 @@ grouping code blocks and other content.
|
||||
|
||||
## Configuration
|
||||
|
||||
This configuration enables content tabs, and allows to nest arbirtrary content
|
||||
This configuration enables content tabs, and allows to nest arbitrary content
|
||||
inside content tabs, including code blocks and ... more content tabs! Add the
|
||||
following lines to `mkdocs.yml`
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
|
||||
@ -30,42 +30,25 @@ markdown_extensions:
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
```
|
||||
|
||||
No further configuration is necessary. Advantages over custom integration:
|
||||
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
|
||||
|
||||
_While it's also possible to integrate [Mermaid.js] using existing
|
||||
third-party plugins[^2], the new native integration is recommended as it
|
||||
ensures interoperability with all Material for MkDocs features._
|
||||
|
||||
[^1]:
|
||||
While all [Mermaid.js] features should work out-of-the-box, Material for
|
||||
MkDocs will currently adjust the fonts and colors for flow charts, sequence
|
||||
diagrams, class diagams, state diagrams and entity relationship diagrams.
|
||||
|
||||
[^2]:
|
||||
If you don't want to use the native integration, [mkdocs-mermaid2-plugin]
|
||||
might be a good alternative. However, note that this plugin cannot be used
|
||||
in conjunction with the [mkdocs-minify-plugin] and doesn't adapt to
|
||||
dark mode.
|
||||
MkDocs will currently only adjust the fonts and colors for flowcharts,
|
||||
sequence diagrams, class diagams, state diagrams and entity relationship
|
||||
diagrams.
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[additional stylesheets]: ../customization.md#additional-css
|
||||
[mkdocs-mermaid2-plugin]: https://github.com/fralau/mkdocs-mermaid2-plugin
|
||||
[mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
|
||||
|
||||
## Usage
|
||||
|
||||
Mermaid diagrams are written as code blocks with the help of the [SuperFences]extension. They must be enclosed with two separate lines containing three
|
||||
backticks.
|
||||
|
||||
[code blocks]: code-blocks.md
|
||||
[SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
|
||||
|
||||
### Using flowcharts
|
||||
|
||||
[Flowcharts] are diagrams that represent workflows or processes. The steps
|
||||
|
||||
@ -5,27 +5,26 @@ template: overrides/main.html
|
||||
# Footnotes
|
||||
|
||||
Footnotes are a great way to add references to supplemental or additional
|
||||
information for a specific section of a document without interrupting the
|
||||
document flow. Material for MkDocs provides the ability to insert inline
|
||||
footnotes and render them at the bottom of the page.
|
||||
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.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Footnotes
|
||||
|
||||
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
|
||||
|
||||
The [Footnotes][2] extension, which is part of the standard Markdown library,
|
||||
adds the ability to add inline footnotes to a document and can be enabled via
|
||||
`mkdocs.yml`:
|
||||
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`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- footnotes
|
||||
```
|
||||
|
||||
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
|
||||
[2]: https://python-markdown.github.io/extensions/footnotes/
|
||||
See additional configuration options:
|
||||
|
||||
- [Footnotes]
|
||||
|
||||
[Footnotes]: ../setup/extensions/python-markdown.md#footnotes
|
||||
|
||||
## Usage
|
||||
|
||||
@ -54,7 +53,7 @@ reference is automatically added.
|
||||
|
||||
#### on a single line
|
||||
|
||||
Short statements can be written on the same line.
|
||||
Short footnotes can be written on the same line.
|
||||
|
||||
_Example_:
|
||||
|
||||
|
||||
@ -6,135 +6,40 @@ template: overrides/main.html
|
||||
|
||||
Material for MkDocs provides support for several HTML elements that can be used
|
||||
to highlight sections of a document or apply specific formatting. Additionally,
|
||||
[Critic Markup][1] is supported, adding the ability to display suggested changes
|
||||
[Critic Markup] is supported, adding the ability to display suggested changes
|
||||
for a document.
|
||||
|
||||
[1]: http://criticmarkup.com/
|
||||
[Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
|
||||
|
||||
## Configuration
|
||||
|
||||
### Critic
|
||||
|
||||
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
|
||||
|
||||
The [Critic][3] extension, which is part of [Python Markdown Extensions][4],
|
||||
allows for the __usage of [Critic Markup][1] to highlight changes__ in a
|
||||
document, and can be enabled via `mkdocs.yml`:
|
||||
This configuration enables support for keyboard keys, highlighting changes
|
||||
to documents, highlighting text and defining sub- and superscript. Add the
|
||||
following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic
|
||||
```
|
||||
|
||||
The following options are supported:
|
||||
|
||||
`mode`{ #mode }
|
||||
|
||||
: :octicons-milestone-24: Default: `view` – This option defines how the markup
|
||||
should be parsed, i.e. whether to just `view` all suggest changes, or
|
||||
alternatively `accept` or `reject` them:
|
||||
|
||||
=== "View changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: view
|
||||
```
|
||||
|
||||
=== "Accept changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: accept
|
||||
```
|
||||
|
||||
=== "Reject changes"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.critic:
|
||||
mode: reject
|
||||
```
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions/
|
||||
|
||||
### BetterEm
|
||||
|
||||
The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4],
|
||||
improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_),
|
||||
and can be enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
```
|
||||
|
||||
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
|
||||
|
||||
### Caret, Mark & Tilde
|
||||
|
||||
The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python
|
||||
Markdown Extensions][4], allow for the __highlighting of text__, as well as
|
||||
__handling sub- and superscripts__:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.caret
|
||||
- pymdownx.keys
|
||||
- pymdownx.mark
|
||||
- pymdownx.tilde
|
||||
```
|
||||
|
||||
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
|
||||
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
|
||||
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
|
||||
- [Critic]
|
||||
- [Caret, Mark & Tilde]
|
||||
- [Keys]
|
||||
|
||||
### Adding keyboard keys
|
||||
|
||||
When [Keys][22] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
Consult the [Python Markdown Extensions][14] documentation to learn about all
|
||||
available key codes.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
++ctrl+alt+del++
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
++ctrl+alt+del++
|
||||
|
||||
[22]: #keys
|
||||
|
||||
### SmartSymbols
|
||||
|
||||
The [SmartSymbols][9] extension, which is also part of [Python Markdown
|
||||
Extensions][4], __converts special characters into their corresponding
|
||||
symbols__, and can be enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.smartsymbols
|
||||
```
|
||||
|
||||
See the [official documentation][9] for a list of supported symbols.
|
||||
|
||||
[9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
|
||||
[Critic]: ../setup/extensions/python-markdown-extensions.md#critic
|
||||
[Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde
|
||||
[Keys]: ../setup/extensions/python-markdown-extensions.md#keys
|
||||
|
||||
## Usage
|
||||
|
||||
### Highlighting changes
|
||||
|
||||
When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
|
||||
ability to _highlight suggested changes_, as well as add _inline comments_ to a
|
||||
document:
|
||||
|
||||
[10]: #critic
|
||||
When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to
|
||||
highlight suggested changes, as well as add inline comments to a document.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -145,7 +50,7 @@ possible {>>and comments can be added inline<<}.
|
||||
|
||||
{==
|
||||
|
||||
Formatting can also be applied to blocks, by putting the opening and closing
|
||||
Formatting can also be applied to blocks by putting the opening and closing
|
||||
tags on separate lines and adding new lines between the tags and the content.
|
||||
|
||||
==}
|
||||
@ -162,7 +67,7 @@ Text can be <del class="critic">deleted</del> and replacement text
|
||||
<div>
|
||||
<mark class="critic block">
|
||||
<p>
|
||||
Formatting can also be applied to blocks, by putting the opening and
|
||||
Formatting can also be applied to blocks by putting the opening and
|
||||
closing tags on separate lines and adding new lines between the tags and
|
||||
the content.
|
||||
</p>
|
||||
@ -171,9 +76,9 @@ Text can be <del class="critic">deleted</del> and replacement text
|
||||
|
||||
### Highlighting text
|
||||
|
||||
When the [Caret, Mark & Tilde][11] extensions are enabled, text can be
|
||||
highlighted with a nicer syntax than using the corresponding `mark`, `ins` and
|
||||
`del` HTML tags:
|
||||
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.
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -189,13 +94,11 @@ _Result_:
|
||||
- ^^This was inserted^^
|
||||
- ~~This was deleted~~
|
||||
|
||||
[11]: #caret-mark-tilde
|
||||
|
||||
### Sub- and superscripts
|
||||
|
||||
When the [Caret & Tilde][11] extensions are enabled, text can be sub- and
|
||||
superscripted with a nicer syntax than using the corresponding `sub` and `sup`
|
||||
HTML tags:
|
||||
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:
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -209,4 +112,20 @@ _Result_:
|
||||
- H~2~0
|
||||
- A^T^A
|
||||
|
||||
[11]: #caret-mark-tilde
|
||||
### Adding keyboard keys
|
||||
|
||||
When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
|
||||
Consult the [Python Markdown Extensions] documentation to learn about all
|
||||
available shortcodes.
|
||||
|
||||
_Example_:
|
||||
|
||||
``` markdown
|
||||
++ctrl+alt+del++
|
||||
```
|
||||
|
||||
_Result_:
|
||||
|
||||
++ctrl+alt+del++
|
||||
|
||||
[Python Markdown Extensions]: [#keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index)
|
||||
|
||||
@ -5,9 +5,11 @@ template: overrides/main.html
|
||||
# Icons + Emojis
|
||||
|
||||
One of the best features of Material for MkDocs is the possibility to use [more
|
||||
than 8.000 icons][1] and thousands of emojis in your project documentation
|
||||
with practically zero additional effort. Furthermore, custom icons can be added
|
||||
and used in `mkdocs.yml`, documents and templates.
|
||||
than 8.000 icons][icon search] and thousands of emojis in your project
|
||||
documentation with practically zero additional effort. Moreover, custom icons
|
||||
can be added and used in `mkdocs.yml`, documents and templates.
|
||||
|
||||
[icon search]: #search
|
||||
|
||||
## Search
|
||||
|
||||
@ -24,19 +26,15 @@ and used in `mkdocs.yml`, documents and templates.
|
||||
</div>
|
||||
<small>
|
||||
:octicons-light-bulb-16:
|
||||
**Tip:** Enter some keywords to find the perfect icon or emoji and click on
|
||||
the shortcode to copy it to your clipboard.
|
||||
**Tip:** Enter some keywords to find icons and emojis and click on the
|
||||
shortcode to copy it to your clipboard.
|
||||
</small>
|
||||
|
||||
## Configuration
|
||||
|
||||
### Emoji
|
||||
|
||||
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
|
||||
|
||||
The [Emoji][3] extension, which is part of [Python Markdown Extensions][4],
|
||||
adds the ability to __integrate emojis and icons__ in the `*.svg` file format,
|
||||
which are inlined when [building your site][5]:
|
||||
This configuration enables the use of icons and emojis by using simple
|
||||
shortcodes which can be discovered through the [icon search]. Add the following
|
||||
lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -47,44 +45,29 @@ markdown_extensions:
|
||||
|
||||
The following icon sets are bundled with Material for MkDocs:
|
||||
|
||||
- :material-material-design: – [Material Design][6]
|
||||
- :fontawesome-brands-font-awesome-flag: – [FontAwesome][7]
|
||||
- :octicons-mark-github-16: – [Octicons][8]
|
||||
- :material-material-design: – [Material Design]
|
||||
- :fontawesome-brands-font-awesome: – [FontAwesome]
|
||||
- :octicons-mark-github-16: – [Octicons]
|
||||
|
||||
You can also add [additional icons][9]. When using emojis, it's recommended to
|
||||
consult the official documentation of [Python Markdown Extensions][3] to learn
|
||||
about configuration options.
|
||||
See additional configuration options:
|
||||
|
||||
[1]: icons-emojis.md#search
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions/
|
||||
[5]: ../creating-your-site.md#building-your-site
|
||||
[6]: https://materialdesignicons.com/
|
||||
[7]: https://fontawesome.com/icons?d=gallery&m=free
|
||||
[8]: https://octicons.github.com/
|
||||
[9]: ../setup/changing-the-logo-and-icons.md#additional-icons
|
||||
- [Emoji]
|
||||
- [Emoji with custom icons]
|
||||
|
||||
### Attribute List
|
||||
|
||||
The [Attribute List][10] 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`
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
```
|
||||
|
||||
[10]: https://python-markdown.github.io/extensions/attr_list/
|
||||
[Material Design]: https://materialdesignicons.com/
|
||||
[FontAwesome]: https://fontawesome.com/icons?d=gallery&m=free
|
||||
[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
|
||||
|
||||
## Usage
|
||||
|
||||
### Using emojis
|
||||
|
||||
Emojis can be integrated in Markdown by putting the shortcode of the emoji
|
||||
between two colons. If you're using [Twemoji][11] (recommended), you can look up
|
||||
the shortcodes at [Emojipedia][12].
|
||||
between two colons. If you're using [Twemoji] (recommended), you can look up
|
||||
the shortcodes at [Emojipedia].
|
||||
|
||||
_Example_:
|
||||
|
||||
@ -96,12 +79,12 @@ _Result_:
|
||||
|
||||
:smile:
|
||||
|
||||
[11]: https://twemoji.twitter.com/
|
||||
[12]: https://emojipedia.org/twitter/
|
||||
[Twemoji]: https://twemoji.twitter.com/
|
||||
[Emojipedia]: https://emojipedia.org/twitter/
|
||||
|
||||
### Using icons
|
||||
|
||||
When [Emoji][13] 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
|
||||
[`.icons`][1] directory, and replacing `/` with `-`:
|
||||
|
||||
@ -119,7 +102,6 @@ _Result_:
|
||||
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
|
||||
- :octicons-repo-push-16: – [`.icons/octicons/repo-push-16.svg`][16]
|
||||
|
||||
[13]: #emoji
|
||||
[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
|
||||
|
||||
@ -78,19 +78,24 @@ but it's always possible to resort to HTML. Using `figure` and `figcaption`, cap
|
||||
_Example_:
|
||||
|
||||
```html
|
||||
<figure>
|
||||
<img src="https://dummyimage.com/600x400/eee/aaa" width="300" />
|
||||
<figure markdown> <!-- (1) -->
|
||||
{ width="300" }
|
||||
<figcaption>Image caption</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
1. :man_raising_hand: Remember to enable the [Markdown in HTML] extension.
|
||||
|
||||
_Result_:
|
||||
|
||||
<figure>
|
||||
<img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–" width="300" />
|
||||
<figure markdown>
|
||||
![Dummy image]{ width="300" }
|
||||
<figcaption>Image caption</figcaption>
|
||||
</figure>
|
||||
|
||||
[Dummy image]: https://dummyimage.com/600x400/f5f5f5/aaaaaa&text=–%20Image%20–
|
||||
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
|
||||
|
||||
### Image lazy-loading
|
||||
|
||||
Modern browsers provide [native support for lazy-loading images][4] through the
|
||||
|
||||
@ -39,7 +39,7 @@ configuring the style:
|
||||
|
||||
: :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 strongly recommended:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
|
||||
@ -24,7 +24,7 @@ theme:
|
||||
|
||||
The following languages are supported:
|
||||
|
||||
<div class="mdx-columns" markdown="1">
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- `af` – Afrikaans
|
||||
- `ar` – Arabic
|
||||
|
||||
@ -16,10 +16,11 @@ syntax extensions for technical writing.
|
||||
|
||||
## Supported extensions
|
||||
|
||||
The following extensions are all supported by Material for MkDocs and therefore _strongly recommended_. Click on each extension to learn about its purpose and
|
||||
The following extensions are all supported by Material for MkDocs and therefore
|
||||
strongly recommended. Click on each extension to learn about its purpose and
|
||||
configuration:
|
||||
|
||||
<div class="mdx-columns" markdown="1">
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [Abbreviations]
|
||||
- [Admonition]
|
||||
|
||||
@ -13,19 +13,13 @@ installed with a supported version.
|
||||
|
||||
## Supported extensions
|
||||
|
||||
The following extensions are all supported by Material for MkDocs and therefore
|
||||
_strongly recommended_. See the [overview][Extensions] page for a minimal and
|
||||
recommended configuration.
|
||||
|
||||
[Extensions]: index.md
|
||||
|
||||
### Arithmatex
|
||||
|
||||
[:octicons-workflow-24: Extension][Arithmatex] ·
|
||||
[:octicons-tag-24: 1.0.0 ... present][Arithmatex support]
|
||||
|
||||
The [Arithmatex] extension allows for rendering of block and inline block
|
||||
equations, and integrates seamlessly with [MathJax][^1] – a library for
|
||||
equations and integrates seamlessly with [MathJax][^1] – a library for
|
||||
mathematical typesetting. Enable it via `mkdocs.yml`:
|
||||
|
||||
[^1]:
|
||||
@ -74,8 +68,8 @@ of [additional JavaScript]:
|
||||
```
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
@ -284,8 +278,8 @@ The following configuration options are supported:
|
||||
```
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
@ -323,7 +317,7 @@ markdown_extensions:
|
||||
|
||||
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.
|
||||
be necessary, but it's strongly recommended anyway.
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
@ -407,8 +401,8 @@ The following configuration options are supported:
|
||||
or `pymdownx-inline` is recommended.
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
@ -478,9 +472,14 @@ MkDocs, as they only impact the Markdown parsing stage. The only exception is
|
||||
the [`class`][Keys options] option, which must not be changed. See the
|
||||
[Keys documentation][Keys] for more information.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Adding keyboard keys]
|
||||
|
||||
[Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
|
||||
[Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
[Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
|
||||
[Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
|
||||
|
||||
### SmartSymbols
|
||||
|
||||
@ -523,10 +522,12 @@ documentation][Snippets] for more information.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
- [Adding a glossary]
|
||||
- [Embedding external files]
|
||||
|
||||
[Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
|
||||
[Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
|
||||
[Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
|
||||
|
||||
### SuperFences
|
||||
@ -566,8 +567,8 @@ The following configuration options are supported:
|
||||
integrated with Material for MkDocs.
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
@ -619,8 +620,8 @@ The following configuration options are supported:
|
||||
```
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
@ -658,7 +659,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 strongly recommended:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -679,8 +680,8 @@ The following configuration options are supported:
|
||||
```
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
See reference for usage:
|
||||
|
||||
|
||||
@ -7,18 +7,12 @@ template: overrides/main.html
|
||||
Material for MkDocs supports a large number of [Python Markdown] extensions,
|
||||
which is part of what makes it so attractive for technical writing. Following
|
||||
is a list of all supported extensions, linking to the relevant sections of the
|
||||
reference for what features they need to be enabled.
|
||||
reference for which features they need to be enabled.
|
||||
|
||||
[Python Markdown]: https://python-markdown.github.io/
|
||||
|
||||
## Supported extensions
|
||||
|
||||
The following extensions are all supported by Material for MkDocs and therefore
|
||||
_strongly recommended_. See the [overview][Extensions] page for a minimal and
|
||||
recommended configuration.
|
||||
|
||||
[Extensions]: index.md
|
||||
|
||||
### Abbreviations
|
||||
|
||||
[:octicons-workflow-24: Extension][Abbreviations] ·
|
||||
@ -129,7 +123,7 @@ No configuration options are available. See reference for usage:
|
||||
[:octicons-tag-24: 1.0.0 ... present][Footnotes support]
|
||||
|
||||
The [Footnotes] extension allows to define footnotes inline with the content,
|
||||
which are then rendered after the Markdown content of a document. Enable it
|
||||
which are then rendered below all Markdown content of a document. Enable it
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
@ -153,8 +147,8 @@ No configuration options are supported. See reference for usage:
|
||||
[:octicons-tag-24: 1.0.0 ... present][Metadata support]
|
||||
|
||||
The [Metadata] extension adds the ability to attach arbitrary key-value pairs
|
||||
to a document via front matter written in YAML syntax before the Markdown. It
|
||||
can be enabled via `mkdocs.yml`:
|
||||
to a document via front matter written in YAML syntax before the Markdown.
|
||||
Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -180,9 +174,9 @@ No configuration options are available. See reference for usage:
|
||||
[:octicons-workflow-24: Extension][Markdown in HTML] ·
|
||||
[:octicons-tag-24: 0.1.0 ... present][Markdown in HTML support]
|
||||
|
||||
The [Markdown in HTML] extension allows the author to write Markdown inside of
|
||||
HTML, which is useful for wrapping Markdown with custom markup. Enable it via
|
||||
`mkdocs.yml`:
|
||||
The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
|
||||
which is useful for wrapping Markdown content with custom elements. Enable it
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -191,8 +185,8 @@ markdown_extensions:
|
||||
|
||||
> By default, Markdown ignores any content within a raw HTML block-level
|
||||
> element. With the `md_in_html` extension enabled, the content of a raw HTML
|
||||
> block-level element can be parsed as Markdown by including a markdown
|
||||
> attribute on the opening tag. The markdown attribute will be stripped from
|
||||
> block-level element can be parsed as Markdown by including a `markdown`
|
||||
> attribute on the opening tag. The `markdown` attribute will be stripped from
|
||||
> the output, while all other attributes will be preserved.
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
@ -290,7 +284,7 @@ The following configuration options are supported:
|
||||
```
|
||||
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, so they may yield unexpected results. Use them at your
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use them at your
|
||||
own risk.
|
||||
|
||||
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
|
||||
@ -345,9 +339,9 @@ nesting, and therefore strongly recommended.
|
||||
[:octicons-workflow-24: Extension][CodeHilite] ·
|
||||
[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support]
|
||||
|
||||
Superseded by [Highlight]. Support for CodeHilite was dropped in version 6.0.0,
|
||||
as [Highlight] has a better integration with other essential extensions like
|
||||
[SuperFences] and [InlineHilite].
|
||||
Superseded by [Highlight]. Support for CodeHilite was dropped in
|
||||
:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other
|
||||
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
|
||||
|
||||
@ -65,7 +65,7 @@ The following options are supported:
|
||||
|
||||
The following languages are supported:
|
||||
|
||||
<div class="mdx-columns" markdown="1">
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- `ar` – Arabic
|
||||
- `da` – Danish
|
||||
|
||||
@ -39,11 +39,11 @@ plugins:
|
||||
|
||||
For example, the page on [setting up site analytics][5] renders as:
|
||||
|
||||
<figure markdown="1">
|
||||
<figure markdown>
|
||||
|
||||
[![Social Cards][6]][6]
|
||||
|
||||
<figcaption markdown="1">
|
||||
<figcaption markdown>
|
||||
|
||||
Want to try it out? Copy the current URL and paste it into [Twitter's Card
|
||||
validator][7] to see how social cards look in action.
|
||||
|
||||
@ -31,11 +31,11 @@ extra:
|
||||
This will render a version selector in the header next to the title of your
|
||||
project:
|
||||
|
||||
<figure markdown="1">
|
||||
<figure markdown>
|
||||
|
||||
[![Version selection][3]][3]
|
||||
|
||||
<figcaption markdown="1">
|
||||
<figcaption markdown>
|
||||
|
||||
A demo is worth a thousand words — check it out at
|
||||
[squidfunk.github.io/mkdocs-material-example-versioning][4]
|
||||
@ -141,8 +141,8 @@ the current page:
|
||||
docs.example.com/0.1/bar/ -> docs.example.com/0.2/
|
||||
```
|
||||
|
||||
<figure markdown="1">
|
||||
<figcaption markdown="1">
|
||||
<figure markdown>
|
||||
<figcaption markdown>
|
||||
|
||||
A demo is worth a thousand words — check it out at
|
||||
[squidfunk.github.io/mkdocs-material-example-versioning][4]
|
||||
|
||||
@ -150,12 +150,6 @@ $admonitions: (
|
||||
left: initial;
|
||||
}
|
||||
}
|
||||
|
||||
// Adjust spacing on last tabbed block container child - if the tabbed
|
||||
// block container is the sole child, it looks better to omit the margin
|
||||
+ .tabbed-set:last-child {
|
||||
margin-top: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user