This is a Draft for reference MkDocs

This page was Created: 2024-08-16

This page was last updated: 2024-09-16

Hello, I'm Opeyemi Okuboyejo

Opeyemi Okuboyejo

MarkDown Basic Syntax

MarkDown Basic Syntax

Image Handling

Watch this YouTube Video

Nice Video

Embed a YouTube Video on page

This is image positioning

Centred image with caption and alt text

Opeyemi Okuboyejo

Centred image with caption and alt text

Profile Image Caption

Clickable Centred image with caption and alt text

Profile Image Caption

Image caption

Image 2 caption

Usage

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:

LeftRight

![Image title](https://dummyimage.com/600x400){ align=left }

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 title](https://dummyimage.com/600x400){ align=right }

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:

<figure markdown="span">
  ![Image title](https://dummyimage.com/600x400){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

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 title](https://dummyimage.com/600x400/){ loading=lazy }

Warning

This is a warning block

Warning

This is a warning block expanded by default

Attention

This is an attention block

Info

This is an attention block

Console

This is an attention block

Integrate with site navigation

Add the following to your mkdocs.yml to see how the Blog plugin can integrate the blog navigation with the overall navigation structure. Note that the only thing you need to specify at this point is the index page for the blog and its path must match the blog_dir setting, which is blog by default:

nav:
  - Home: index.md
  - Install: install.md
  - Usage: usage.md
  - Blog:
     - blog/index.md

You will notice that "Blog" is duplicated in the navigation structure. To avoid this, you can use the navigation.indexes feature to make the blog index the seciton index page for the blog:

theme:
  name: material
  features:
    - navigation.indexes

Stand-alone blog

If what you need is a stand-alone blog instead of one that is integrated with a larger site, this can be done by using the blog_dir configuration option. To see how this is done, see setting up a blog. The rest of the tutorial assumes that you are integrating the blog with a wider site.

Adding pages

You can add additional pages to the blog section by putting them into docs/blog (and adding them to the navigation). The blog archive will be added to the navigation after these pages.

How to visualize the collected feedback ratings?

To visualize feedback ratings you'll need to create a custom report with [Google Analytics] that will quickly show you the worst- and best-rated pages of your project documentation.

1. Go to your Google Analytics dashboard

2. Go to the configure page on the left hand menu, then select custom definitions

3. Click the custom metrics tab and then create custom metrics, enter the following values:

   • Metric name: Page helpful
   • Description: Was this page helpful?
   • Event parameter: data
   • Unit of measurement: Standard

4. Go to the explore page on the left hand menu, create a new blank exploration

5. Configure the report as follows:

   • Dimensions: Add Event name and Page location
   • Metrics: Add Event count and Page helpful (the custom metric created in step 3)
   • Rows: Page location
   • Values: Drag in both Event count and Page helpful
   • Filters: Add a new filter for Event name / exactly matches / feedback

Delay in data availability

The report may take 24 hours or longer to begin displaying data

Now, after you've saved the report and collected some feedback ratings, you'll have a list of all pages with the total number of ratings, and an average rating per page. This should help you identify pages that need to be improved:

Google Analytics 4 does not support average values

To our knowledge, Google Analytics 4 has currently no feature that allows to define a custom calculated metric to compute the average rating of a page. See #5740.

[![feedback report]][feedback report]

Getting started

Material for MkDocs is a powerful documentation framework on top of MkDocs, a static site generator for project documentation.¹ If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommend using docker.

Installation

with pip recommended

Material for MkDocs is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install Material for MkDocs with:

Latest9.x

pip install mkdocs-material

pip install mkdocs-material=="9.*" # (1)!

1. Material for MkDocs uses semantic versioning², which is why it's a good idea to limit upgrades to the current major version.

   This will make sure that you don't accidentally upgrade to the next major version, which may include breaking changes that silently corrupt your site. Additionally, you can use pip freeze to create a lockfile, so builds are reproducible at all times:

   pip freeze > requirements.txt
   

   Now, the lockfile can be used for installation:

   pip install -r requirements.txt
   

This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.

---

How to set up Material for MkDocs by @james-willett – 15m – Learn how to create and host a documentation site using Material for MkDocs on GitHub Pages in a step-by-step guide.

---

Tip

If you don't have prior experience with Python, we recommend reading Using Python's pip to Manage Your Projects' Dependencies, which is a really good introduction on the mechanics of Python package management and helps you troubleshoot if you run into errors.

with docker

The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Open up a terminal and pull the image with:

Latest9.x

docker pull squidfunk/mkdocs-material

docker pull squidfunk/mkdocs-material:9

The mkdocs executable is provided as an entry point and serve is the default command. If you're not familiar with Docker don't worry, we have you covered in the following sections.

The following plugins are bundled with the Docker image:

• mkdocs-minify-plugin
• mkdocs-redirects

Green Bar colapsed

this is sample text

How to add plugins to the Docker image?

Material for MkDocs only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily:

Material for MkDocsInsiders

Create a Dockerfile and extend the official image:

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox

Clone or fork the Insiders repository, and create a file called user-requirements.txt in the root of the repository. Then, add the plugins that should be installed to the file, e.g.:

mkdocs-macros-plugin
mkdocs-glightbox

Next, build the image with the following command:

docker build -t squidfunk/mkdocs-material .

The new image will have additional packages installed and can be used exactly like the official image.

with git

Material for MkDocs can be directly used from GitHub by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:

git clone https://github.com/squidfunk/mkdocs-material.git

Next, install the theme and its dependencies with:

pip install -e mkdocs-material

---

icon: simple/terraform

Terraform Page

Terraform AWS

resource "aws_instance" "Server" {
  ami           = "ami-0b8b44ec9a8f90422"
  instance_type = var.instance_type

  # key_name = "OpeyemiTechPro-KeyPair.ppk"
user_data = file("./userdata.sh")

  key_name = var.key_pair_name

  tags = {
    Name = "Server"
  }
}

This is page 2 contents

This is an annotation (1)

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

1. I'm an annotation!
2. I'm an annotation as well!

import tensorflow as tf
def whatever()

Code Annotation Examples

Codeblocks

Some code goes here.

Plain codeblock

A plain codeblock:

Some code here
def myfunction()
// some comment

Code for a specific language

Some more code with the py at the start:

import tensorflow as tf
def whatever()

With a title

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]

With line numbers

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]

Annotated Text

This is annotated text (1) Click the annotation to see more details { .annotate} 1. ### This text has been annotated as you can see 2. This is line 2 of the annotation def myfunction() 3. ``` tf resource "aws_instance" "Server" { ami = "ami-0b8b44ec9a8f90422" instance_type = var.instance_type

# key_name = "OpeyemiTechPro-KeyPair.ppk" user_data = file("./userdata.sh")

key_name = var.key_pair_name

tags = { Name = "Server" } }

#### Highlighting lines

``` py hl_lines="2 3"
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]

Icons and Emojis

---

icon: material/button-cursor

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.

Configuration

This configuration allows to add attributes to all inline- and block-level elements with a simple syntax, turning any link into a button. Add the following lines to mkdocs.yml:

markdown_extensions:
  - attr_list

See additional configuration options:

• Attribute Lists

Usage

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.

[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.

[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.

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

Send

---

icon: simple/amazonwebservices

AWS Projects

Warning

This is a warning block

---

Attention

This is an attention block

Integrate with site navigation

Add the following to your mkdocs.yml to see how the Blog plugin can integrate the blog navigation with the overall navigation structure. Note that the only thing you need to specify at this point is the index page for the blog and its path must match the blog_dir setting, which is blog by default:

nav:
  - Home: index.md
  - Install: install.md
  - Usage: usage.md
  - Blog:
     - blog/index.md

You will notice that "Blog" is duplicated in the navigation structure. To avoid this, you can use the navigation.indexes feature to make the blog index the seciton index page for the blog:

theme:
  name: material
  features:
    - navigation.indexes

Stand-alone blog

If what you need is a stand-alone blog instead of one that is integrated with a larger site, this can be done by using the blog_dir configuration option. To see how this is done, see setting up a blog. The rest of the tutorial assumes that you are integrating the blog with a wider site.

Adding pages

You can add additional pages to the blog section by putting them into docs/blog (and adding them to the navigation). The blog archive will be added to the navigation after these pages.

Changing the colors

As any proper Material Design implementation, Material for MkDocs supports Google's original color palette, which can be easily configured through mkdocs.yml. Furthermore, colors can be customized with a few lines of CSS to fit your brand's identity by using CSS variables.

Configuration

Color palette

Color scheme

Material for MkDocs supports two color schemes: a light mode, which is just called default, and a dark mode, which is called slate. The color scheme can be set via mkdocs.yml:

theme:
  palette:
    scheme: default

Click on a tile to change the color scheme:

default slate

Primary color

The primary color is used for the header, the sidebar, text links and several other components. In order to change the primary color, set the following value in mkdocs.yml to a valid color name:

theme:
  palette:
    primary: indigo

Click on a tile to change the primary color:

red pink purple deep purple indigo blue light blue cyan teal green light green lime yellow amber orange deep orange brown grey blue grey black white

See our guide below to learn how to set custom colors.

Accent color

The accent color is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. It can be changed in mkdocs.yml by choosing a valid color name:

theme:
  palette:
    accent: indigo

Click on a tile to change the accent color:

red pink purple deep purple indigo blue light blue cyan teal green light green lime yellow amber orange deep orange

See our guide below to learn how to set custom colors.

Color palette toggle

Offering a light and dark color palette makes your documentation pleasant to read at different times of the day, so the user can choose accordingly. Add the following lines to mkdocs.yml:

theme:
  palette: # (1)!

    # Palette toggle for light mode
    - scheme: default
      toggle:
        icon: material/brightness-7 # (2)!
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

1. Note that the theme.palette setting is now defined as a list.

2. Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

This configuration will render a color palette toggle next to the search bar. Note that you can also define separate settings for primary and accent per color palette.

The following properties must be set for each toggle:

This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations:

• + – material/brightness-7 + material/brightness-4
• + – material/toggle-switch + material/toggle-switch-off-outline
• + – material/weather-night + material/weather-sunny
• + – material/eye + material/eye-outline
• + – material/lightbulb + material/lightbulb-outline

This property is used as the toggle's title attribute and should be set to a discernable name to improve accessibility. It's rendered as a tooltip.

System preference

Each color palette can be linked to the user's system preference for light and dark appearance by using a media query. Simply add a media property next to the scheme definition in mkdocs.yml:

theme:
  palette:

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

When the user first visits your site, the media queries are evaluated in the order of their definition. The first media query that matches selects the default color palette.

Automatic light / dark mode

Newer operating systems allow to automatically switch between light and dark appearance during day and night times. Material for MkDocs adds support for automatic light / dark mode, delegating color palette selection to the user's operating system. Add the following lines to mkdocs.yml:

theme:
  palette:

    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default # (1)!
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

1. You can also define separate settings for primary and accent per color palette, i.e. different colors for light and dark mode.

Material for MkDocs will now change the color palette each time the operating system switches between light and dark appearance, even when the user doesn't reload the site.

Customization

Custom colors

Material for MkDocs implements colors using CSS variables (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 style sheet and tweak the values of the CSS variables.

First, set the primary or accent values in mkdocs.yml to custom, to signal to the theme that you want to define custom colors, e.g., when you want to override the primary color:

theme:
  palette:
    primary: custom

Let's say you're YouTube, and want to set the primary color to your brand's palette. Just add:

docs/stylesheets/extra.css mkdocs.yml

:root {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
}

extra_css:
  - stylesheets/extra.css

See the file containing the color definitions for a list of all CSS variables.

Custom color schemes

Besides overriding specific colors, you can create your own, named color scheme by wrapping the definitions in a [data-md-color-scheme="..."] attribute selector, which you can then set via mkdocs.yml as described in the color schemes section:

docs/stylesheets/extra.css mkdocs.yml

[data-md-color-scheme="youtube"] {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
}

theme:
  palette:
    scheme: youtube
extra_css:
  - stylesheets/extra.css

Additionally, the slate color scheme defines all of it's colors via hsla color functions and deduces its colors from the --md-hue CSS variable. You can tune the slate theme with:

[data-md-color-scheme="slate"] {
  --md-hue: 210; /* (1)! */
}

1. The hue value must be in the range of [0, 360]

---

icon: material/alert-outline

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.

Configuration

This configuration enables admonitions, allows to make them collapsible and to nest arbitrary content inside admonitions. Add the following lines to mkdocs.yml:

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

See additional configuration options:

• Admonition
• Details
• SuperFences

Admonition icons

Each of the supported admonition types has a distinct icon, which can be changed to any icon bundled with the theme, or even a custom icon. Add the following lines to mkdocs.yml:

theme:
  icon:
    admonition:
      <type>: <icon> # (1)!

1. Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:

Expand to show alternate icon sets

Octicons FontAwesome

theme:
  icon:
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16

theme:
  icon:
    admonition:
      note: fontawesome/solid/note-sticky
      abstract: fontawesome/solid/book
      info: fontawesome/solid/circle-info
      tip: fontawesome/solid/bullhorn
      success: fontawesome/solid/check
      question: fontawesome/solid/circle-question
      warning: fontawesome/solid/triangle-exclamation
      failure: fontawesome/solid/bomb
      danger: fontawesome/solid/skull
      bug: fontawesome/solid/robot
      example: fontawesome/solid/flask
      quote: fontawesome/solid/quote-left

Usage

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:

!!! 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:

!!! 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:

!!! 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:

??? 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:

???+ 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:

inline end 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.

!!! 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.

!!! 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.

Customization

Classic admonitions

Prior to version , admonitions had a slightly different appearance:

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.

If you want to restore this appearance, add the following CSS to an additional style sheet:

docs/stylesheets/extra.css mkdocs.yml

.md-typeset .admonition,
.md-typeset details {
  border-width: 0;
  border-left-width: 4px;
}

extra_css:
  - stylesheets/extra.css

Custom admonitions

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 folder and add the following CSS to an additional style sheet:

docs/stylesheets/extra.css mkdocs.yml

: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);
}
.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);
}

extra_css:
  - stylesheets/extra.css

After applying the customization, you can use the custom admonition type:

!!! 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.

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.

---

1. Previously, some of the supported types defined more than one qualifier. For example, authors could use summary or tldr as alternative qualifiers to render an abstract admonition. As this increased the size of the CSS that is shipped with Material for MkDocs, the additional type qualifiers are now all deprecated and will be removed in the next major version. This will also be mentioned in the upgrade guide. ↩↩↩

2. Note that improvements of existing features are sometimes released as patch releases, like for example improved rendering of content tabs, as they're not considered to be new features. ↩

Comments