Making your docs shine ¶

This is a great reference guide to many advanced features of Mkdocs, but doesn't necessarily explain things well.

Code blocks ¶

Code blocks can be rendered with a few mkdocs extensions. Add to your mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.inlinehilite

Then you can use code blocks in your markdown like this:

```python
def hello_world():
    print("Hello, world!")
```

Displays as

def hello_world():
    print("Hello, world!")

Emojis ¶

Emojis can can be added with the mkdocs markdown extension pymdownx.emoji. To use it, add the following to your mkdocs.yml:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Then you can use emojis in your markdown like :cat: or :rainbow:.

Admonitions ¶

Admonitions are a general part of doc making libraries. To use mkdocs style admonitions, add the following to your mkdocs.yml:

markdown_extensions:
  - admonition

Then you can use admonitions in your markdown like this:

!!! note "Note Title"
    This is a note admonition. It can contain **bold text**, *italic text*, and even [links](https://www.example.com).

Displays as

Note Title

This is a note admonition. It can contain bold text, italic text, and even links.

Cross-references ¶

[Versioning](versioning.md) will link as Versioning.

[Versioning Sub Header](versioning.md#versioning-frameworks) will link to a sub-header as Versioning Sub Header and link directly to the section!

Math ¶

Math can be added with the mkdocs markdown extension pymdownx.arithmatex. But you also need to have javascript at runtime. To use it, add the following to your mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex

extra_javascript:
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

$E = mc^2$ inline math

$E = mc^2$

$$\int_0^\infty e^{-x} dx = 1$$ block form

\[\int_0^\infty e^{-x} dx = 1\]