跳转至

MkDocs 语法学习

Welcome to MkDocs

For full documentation visit mkdocs.org.

Commands

  • mkdocs new [dir-name] - Create a new project.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.

How to upgrade

Upgrade to the latest version with:

Bash
1
pip install --upgrade --force-reinstall mkdocs-material

Show the currently installed version with:

Bash
1
pip show mkdocs-material

Project layout

Text Only
1
2
3
4
mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Admonitions

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

Admonitions follow a simple syntax: a block starts with !!!, followed by a single keyword used as a type qualifier. The content of the block follows on the next line, indented by four spaces:

Admonition
1
2
3
4
5
!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Changing the title

By default, the title will equal the type qualifier in titlecase. However, it can be changed by adding a quoted string containing valid Markdown (including links, formatting, ...) after the type qualifier:

Admonition with custom title
1
2
3
4
5
!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Phasellus posuere in sem ut cursus

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Removing the title

Similar to changing the title, the icon and title can be omitted entirely by adding an empty string directly after the type qualifier. Note that this will not work for collapsible blocks:

Admonition without title
1
2
3
4
5
!!! note ""

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

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.

Collapsible blocks

When Details is enabled and an admonition block is started with ??? instead of !!!, the admonition is rendered as a collapsible block with a small toggle on the right side:

Admonition, collapsible
1
2
3
4
5
??? note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Adding a + after the ??? token renders the block expanded:

Admonition, collapsible and initially expanded
1
2
3
4
5
???+ note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Inline blocks

Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing them to the right using the inline + end modifiers, or to the left using only the inline modifier:

Lorem ipsum

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
1
2
3
4
5
6
7
!!! info inline end "Lorem ipsum"

    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.

Use inline end to align to the right (left for rtl languages).

Lorem ipsum

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
1
2
3
4
5
6
7
!!! info inline "Lorem ipsum"

    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.

Use inline to align to the left (right for rtl languages).

Important: admonitions that use the inline modifiers must be declared prior to the content block you want to place them beside. If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g., on mobile viewports.

Supported types

Following is a list of type qualifiers provided by Material for MkDocs, whereas
the default type, and thus fallback for unknown type qualifiers, is note:

Note

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.

Abstract

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Info

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Tip

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Success

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Question

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Warning

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Failure

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Danger

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Bug

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Example

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Quote

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Buttons

Material for MkDocs provides dedicated styles for primary and secondary buttons that can be added to any link, label or button element. This is especially useful for documents or landing pages with dedicated call-to-actions.

Adding buttons

In order to render a link as a button, suffix it with curly braces and add the .md-button class selector to it. The button will receive the selected primary color and accent color if active.

Button
1
[Subscribe to our newsletter](#){ .md-button }

Subscribe to our newsletter

Adding primary buttons

If you want to display a filled, primary button (like on the landing page of Material for MkDocs), add both, the .md-button and .md-button--primary CSS class selectors.

Button, primary
1
[Subscribe to our newsletter](#){ .md-button .md-button--primary }

Subscribe to our newsletter

Adding icon buttons

Of course, icons can be added to all types of buttons by using the icon syntax together with any valid icon shortcode, which can be easily found with a few keystrokes through our icon search.

Button with icon
1
[Send :fontawesome-solid-paper-plane:](#){ .md-button }

Send

Content tabs

Grouping code blocks

Code blocks are one of the primary targets to be grouped, and can be considered a special case of content tabs, as tabs with a single code block are always rendered without horizontal spacing:

Content tabs with code blocks
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
=== "C"

    ``` c
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```
C
1
2
3
4
5
6
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}
C++
1
2
3
4
5
6
#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

Grouping other content

When a content tab contains more than one code block, it is rendered with horizontal spacing. Vertical spacing is never added, but can be achieved by nesting tabs in other blocks:

Content tabs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci
  • Sed sagittis eleifend rutrum
  • Donec vitae suscipit est
  • Nulla tempor lobortis orci
  1. Sed sagittis eleifend rutrum
  2. Donec vitae suscipit est
  3. Nulla tempor lobortis orci

Embedded content

When SuperFences is enabled, content tabs can contain arbitrary nested content, including further content tabs, and can be nested in other blocks like admonitions or blockquotes:

Content tabs in admonition
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
!!! example

    === "Unordered List"

        ``` markdown
        * Sed sagittis eleifend rutrum
        * Donec vitae suscipit est
        * Nulla tempor lobortis orci
        ```

    === "Ordered List"

        ``` markdown
        1. Sed sagittis eleifend rutrum
        2. Donec vitae suscipit est
        3. Nulla tempor lobortis orci
        ```

Example

Markdown
1
2
3
* Sed sagittis eleifend rutrum
* Donec vitae suscipit est
* Nulla tempor lobortis orci
Markdown
1
2
3
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci

Footnotes

Adding footnote references

A footnote reference must be enclosed in square brackets and must start with a caret ^, directly followed by an arbitrary identifier, which is similar to the standard Markdown link syntax.

Text with footnote references
1
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

Lorem ipsum1 dolor sit amet, consectetur adipiscing elit.2

Adding footnote content

The footnote content must be declared with the same identifier as the reference. It can be inserted at an arbitrary position in the document and is always rendered at the bottom of the page. Furthermore, a backlink to the footnote reference is automatically added.

on a single line

Short footnotes can be written on the same line:

Footnote
1
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Jump to footnote

on multiple lines

Paragraphs can be written on the next line and must be indented by four spaces:

Footnote
1
2
3
4
[^2]:
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Jump to footnote

Grids

Grids come in two flavors: card grids, which wrap each element in a card that levitates on hover, and generic grids, which allow to arrange arbitrary block elements in a rectangular shape.

Using card grids

Card grids wrap each grid item with a beautiful hover card that levitates on hover. They come in two slightly different syntaxes: list and block syntax, adding support for distinct use cases.

List syntax

The list syntax is essentially a shortcut for card grids, and consists of an unordered (or ordered) list wrapped by a div with both, the grid and cards classes:

Card grid
1
2
3
4
5
6
7
8
<div class="grid cards" markdown>

- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>
  • HTML for content and structure
  • JavaScript for interactivity
  • CSS for text running out of boxes
  • Internet Explorer ... huh?

List elements can contain arbitrary Markdown, as long as the surrounding div defines the markdown attribute. Following is a more complex example, which includes icons and links:

Card grid, complex example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`mkdocs-material`](#) with [`pip`](#) and get up
    and running in minutes

    [:octicons-arrow-right-24: Getting started](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

    Focus on your content and generate a responsive and searchable static site

    [:octicons-arrow-right-24: Reference](#)

-   :material-format-font:{ .lg .middle } __Made to measure__

    ---

    Change the colors, fonts, language, icons, logo and more with a few lines

    [:octicons-arrow-right-24: Customization](#)

-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__

    ---

    Material for MkDocs is licensed under MIT and available on [GitHub]

    [:octicons-arrow-right-24: License](#)

</div>

  • Set up in 5 minutes

    Install [mkdocs-material][mkdocs-material] with [pip][pip] and get up and running in minutes

    Getting started

  • It's just Markdown

    Focus on your content and generate a responsive and searchable static site

    Reference

  • Made to measure

    Change the colors, fonts, language, icons, logo and more with a few lines

    Customization

  • Open Source, MIT

    Material for MkDocs is licensed under MIT and available on [GitHub]

    License

If there's insufficient space to render grid items next to each other, the items will stretch to the full width of the viewport, e.g. on mobile viewports. If there's more space available, grids will render in items of 3 and more, e.g. when hiding both sidebars.

Block syntax

The block syntax allows for arranging cards in grids together with other elements, as explained in the section on generic grids. Just add the card class to any block element inside a grid:

Card grid, blocks
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<div class="grid" markdown>

:fontawesome-brands-html5: __HTML__ for content and structure
{ .card }

:fontawesome-brands-js: __JavaScript__ for interactivity
{ .card }

:fontawesome-brands-css3: __CSS__ for text running out of boxes
{ .card }

> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>

HTML for content and structure

JavaScript for interactivity

CSS for text running out of boxes

Internet Explorer ... huh?

While this syntax may seem unnecessarily verbose at first, the previous example shows how card grids can now be mixed with other elements that will also stretch to the grid.

Using generic grids

Generic grids allow for arranging arbitrary block elements in a grid, including admonitions, code blocks, content tabs and more. Just wrap a set of blocks by using a div with the grid class:

Generic grid
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<div class="grid" markdown>

=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci

``` title="Content tabs"
=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci
```

</div>
  • Sed sagittis eleifend rutrum
  • Donec vitae suscipit est
  • Nulla tempor lobortis orci
  1. Sed sagittis eleifend rutrum
  2. Donec vitae suscipit est
  3. Nulla tempor lobortis orci
Content tabs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
=== "Unordered list"

    * Sed sagittis eleifend rutrum
    * Donec vitae suscipit est
    * Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci

Images

Image alignment

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:

Image, aligned to left
1
![Image title](assets/IMG-20240527191528564.png){ align=left }

Image title

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.

Image, aligned to right
1
![Image title](assets/IMG-20240527191528564.png){ align=right }

Image title

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.

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.

Why is there no centered alignment?

The align attribute doesn't allow for centered alignment, which is why this option is not supported by Material for MkDocs. Instead, the image captions syntax can be used, as captions are optional.

Image captions

Sadly, the Markdown syntax doesn't provide native support for image captions, but it's always possible to use the Markdown in HTML extension with literal figure and figcaption tags:

Image with caption
1
2
3
4
<figure markdown="span">
  ![Image title](assets/IMG-20240527191528564.png){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>
Image title
Image caption

Image lazy-loading

Modern browsers provide native support for lazy-loading images through the loading=lazy directive, which degrades to eager-loading in browsers without support:

Image, lazy-loaded
1
![Image title](assets/IMG-20240527191528564.png){ loading=lazy }

Image title

Light and dark mode

If you added a color palette toggle and want to show different images for light and dark color schemes, you can append a #only-light or #only-dark hash fragment to the image URL:

Image, different for light and dark mode
1
2
![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![Image title](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)

Requirements when using custom color schemes

The built-in color schemes define the aforementioned hash fragments, but if you're using custom color schemes, you'll also have to add the following selectors to your scheme, depending on whether it's a light or dark scheme:

CSS
1
2
3
4
[data-md-color-scheme="custom-light"] img[src$="#only-dark"],
[data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
  display: none; /* Hide dark images in light mode */
}
CSS
1
2
3
4
[data-md-color-scheme="custom-dark"] img[src$="#only-light"],
[data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
  display: none; /* Hide light images in dark mode */
}

Remember to change "custom-light" and "custom-dark" to the name of your scheme.

Tooltips

Adding tooltips

The Markdown syntax allows to specify a title for each link, which will render as a beautiful tooltip when improved tooltips are enabled. Add a tooltip to a link with the following lines:

Link with tooltip, inline syntax
1
[Hover me](https://example.com "I'm a tooltip!")

Hover me

Tooltips can also be added to link references:

Link with tooltip, reference syntax
1
2
3
[Hover me][example]

  [example]: https://example.com "I'm a tooltip!"

Hover me

For all other elements, a title can be added by using the [Attribute Lists] extension:

Icon with tooltip
1
:material-information-outline:{ title="Important information" }

Adding abbreviations

Abbreviations can be defined by using a special syntax similar to URLs and footnotes, starting with a * and immediately followed by the term or acronym to be associated in square brackets:

Text with abbreviations
1
2
3
4
The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

The HTML specification is maintained by the W3C.

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩

  2. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. ↩