mkdocs-material/docs/reference/index.md

Reference

Material for MkDocs is packed with many great features that make technical writing a joyful activity. This section of the documentation explains how to set up a page, and showcases all available specimen that can be used directly from within Markdown files.

Configuration

Usage

Setting the page title

Each page has a designated title, which is used in the navigation sidebar, for social cards and in other places. While MkDocs attempts to automatically determine the title of a page in a four step process, the title can also be explicitly set with the front matter title property:

---
title: Lorem ipsum dolor sit amet # (1)!
---

# Page title
...

1. This line sets the title inside the HTML document's head for the generated page to the given value. Note that the site title, which is set via site_name, is appended with a dash.

Setting the page description

A Markdown file can include a description that is added to the meta tags of a page, and is also used for social cards. It's a good idea to set a site_description in mkdocs.yml as a fallback value if the author does not explicitly define a description for a Markdown file:

---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
---

# Page title
...

1. This line sets the meta tag containing the description inside the document head for the current page to the provided value.

Setting the page icon

An icon can be assigned to each page, which is then rendered as part of the navigation sidebar, as well as navigation tabs, if enabled. Use the front matter icon property to reference an icon, adding the following lines at the top of a Markdown file:

---
icon: material/emoticon-happy # (1)!
---

# Page title
...

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:

Setting the page status

A status can be assigned to each page, which is then displayed as part of the navigation sidebar. First, associate a status identifier with a description by adding the following to mkdocs.yml:

extra:
  status:
    <identifier>: <description> # (1)!

1. The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a status Recently added, you can set new as an identifier:

   extra:
     status:
       new: Recently added
   

The page status can now be set with the front matter status property. For example, you can mark a page as new with the following lines at the top of a Markdown file:

---
status: new
---

# Page title
...

The following status identifiers are already defined:

• :material-alert-decagram: – new
• :material-trash-can: – deprecated

You can define a custom page status this way but if you want it to have an icon other than the default one you need to also configure that in your extra.css. We have an example for a custom page status to get you started.

Setting the page subtitle

Each page can define a subtitle, which is then rendered below the title as part of the navigation sidebar by using the front matter subtitle property, and adding the following lines:

---
subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
---

# Page title
...

Setting the page template

If you're using theme extension and created a new page template in the overrides directory, you can enable it for a specific page. Add the following lines at the top of a Markdown file:

---
template: custom.html
---

# Page title
...

??? question "How to set a page template for an entire folder?"

With the help of the [built-in meta plugin], you can set a custom template
for an entire section and all nested pages, by creating a `.meta.yml` file
in the corresponding folder with the following content:

``` yaml
template: custom.html
```

Customization

Using metadata in templates

:material-check-all: on all pages

In order to add custom meta tags to your document, you can extend the theme and override the extrahead block, e.g. to add indexing policies for search engines via the robots property:

{% extends "base.html" %}

{% block extrahead %}
  <meta name="robots" content="noindex, nofollow" />
{% endblock %}

:material-check: on a single page

If you want to set a meta tag on a single page, or want to set different values for different pages, you can use the page.meta object inside your template override, e.g.:

{% extends "base.html" %}

{% block extrahead %}
  {% if page and page.meta and page.meta.robots %}
    <meta name="robots" content="{{ page.meta.robots }}" />
  {% else %}
    <meta name="robots" content="index, follow" />
  {% endif %}
{% endblock %}

You can now use robots exactly like title and description to set values. Note that in this case, the template defines an else branch, which would set a default if none was given.