Skip to content

Material for MkDocs

Installations

pip install mkdocs-material

Create a new site

$ mkdocs new my-site
$ tree
tree
.
└── my-site
    ├── docs
    │   └── index.md
    └── mkdocs.yml

2 directories, 2 files

Configurations

Minimal Configuration

theme:
  name: material

Change the Colors

theme:
  name: material
  palette:
  - scheme: default
    primary: teal
    accent: amber
    toggle:
      icon: material/lightbulb
      name: Switch to light mode
  - scheme: slate
    primary: teal
    accent: amber
    toggle:
      icon: material/lightbulb-outline
      name: Switch to dark mode

theme:
  features:
    - navigation.tabs
    # - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.indexes # Requires `index.md` at the beginning of a section
    - navigation.top # Back to top button
nav:
  - Section:
    - section/index.md
    - Page 1: section/page-1.md
    ...
    - Page n: section/page-n.md

plugins:
  - search:
      lang: 
        - en
        - ja
theme:
  features:
    - search.suggest
    - search.highlight

Abbreviation

markdown_extensions:
  - abbr
  - pymdownx.snippets

exp:

The HTML specification is maintained by the W3C.

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

Admonitions

Config

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Basic Usage

!!! note
    Note

Supported Types

Change the Title

!!! note "title"

    Customized title

Remove the Title

!!! note ""

    No title

Collapsible blocks

??? note

    Collapsed block

???+ note

    Rendered open block

Buttons

markdown_extensions:
  - attr_list

[Text](#<link>){ .md-button }
[Text](#<link>){ .md-button .md-button--primary }

Code Blocks

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

Highlight

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
  • Line numbers: hl_lines="2 3"
  • Line number range: hl_lines="2-3"
  • Inline code blocks: range()

Content tab

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

Usage

Data Table

markdown_extensions:
  - tables

sortable table

Footnotes

footnotes

Formatting

formatting keyboard keys

Icons and Emojis

search

Images

images

List

lists

Preview

mkdocs serve

Build

mkdocs build

Plug-ins

MkDocs wiki

Mermaid

pip install mkdocs-mermaid2-plugin

plugins:
    - search
    - mermaid2
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid

Example

graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]

Tooltip

🔗Homepage

Example

Options

mkdocstring

Jupyter Notebook

Table

🔗GitHub repo

PDF

🔗Homepage