Skip to content

Create custom statuses for pages in Material for MkDocs

The Material theme for the MkDocs static site generator has a Status feature. You can use frontmatter to mark a page as either new or deprecated, and the theme gives it an icon in the navigation.

Recently, at n8n, I wanted to mark pages as beta to signal they're documentation for a beta feature. I didn't want to use new and its default icon for this, so had to add a custom status.

This is was the result:

Screenshot of a site navigation menu. One entry has a small grey rectangle next to it, with the word beta written in white.

Enable the feature

Start by enabling the status feature in your mkdocs.yml in the extra section:

1
2
3
extra:
  status:
    <identifier>: <description>

For a beta status, I put:

1
2
3
extra:
  status:
    beta: This feature is in beta

The description shows up when a user hovers over the status icon in the navigation.

Set the page status

To tag a page as beta, set the status in the YAML frontmatter at the top of the page:

1
2
3
4
5
6
7
---
# other frontmatter
status: beta
# other frontmatter
---

# page contents

Create a style for your status

You probably already have extra CSS files set up to customise your site. If not, follow the instructions for adding Additional CSS.

In your CSS file, create a new class that includes the custom status name:

1
2
3
.md-status--<status-name>::after {
    /* styles */
}

For a beta status, I added:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
.md-status--beta::after {
    background-color: var(--color-background-dark);
    border-radius: 0.2rem;
    color: white;
    content: "beta";
    font-size: 0.5rem;
    height: auto;       
    padding: 0.1rem;
    -webkit-mask-image: none;
    width: auto;
}

Setting the text colour to white interfered with a hover effect, causing the status tag to disappear on hover, so I also added:

1
2
3
.md-status:hover:after {
   background-color: var(--color-text-base);
}

This is was the result:

Screenshot of a site navigation menu. One entry has a small grey rectangle next to it, with the word beta written in white.

Explanation

The key code for this feature is in the Material theme's nav-item.html template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{% macro render_status(nav_item, type) %}
  <!-- set the element's class based on the status name -->
  {% set class = "md-status md-status--" ~ type %}

  <!-- Render icon with title (or tooltip), if given -->
  {% if config.extra.status and config.extra.status[type] %}
    <span
      class="{{ class }}"
      title="{{ config.extra.status[type] }}"
    >
    </span>

  <!-- Render icon only -->
  {% else %}
    <span class="{{ class }}"></span>
  {% endif %}
{% endmacro %}

The theme determines the look and feel of the status icon in the navigation using the CSS class name. As the theme has built-in support for new and deprecated, it provides styles for these. By adding a class with the name format .md-status--<status-name>, where <status-name> is the status you assign to the page, you can add whatever icon or text you want.

Wrap up

Another niche Material for MkDocs guide, though I think Prevent MkDocs from replacing tabs with spaces in code blocks still holds the record for most-niche post. As usual, I'm not 100% certain I've done things in the best or most elegant way, but it works, and got done in a few minutes hours before feature release, so I'm ok with quick-and-working.

Hire me for a docs consultation