Meta tags¶

In HTML, meta tags allow to provide additional metadata for a document, e.g. page titles and descriptions, additional assets to be loaded, and Open Graph data. While arbitrary metadata can always be added via customization, some common meta tags can be configured.

Configuration¶

Metadata¶

The Metadata extension, which is part of the standard Markdown library, adds the ability to add front matter to a document and can be enabled via mkdocs.yml:

markdown_extensions:
  - meta

Front matter is written as a series of key-value pairs at the beginning of the Markdown document, delimited by a blank line which ends the YAML context.

Usage¶

Setting the page title¶

If the Metadata extension is enabled, the page title can be overridden on a per-document basis with custom front matter:

---
title: Lorem ipsum dolor sit amet
---

# Document title
...

This will set the title tag inside the document head for the current page to the provided value. Note that the site title is appended using a dash as a separator, which is the default behavior.

Setting the page description¶

If the Metadata extension is enabled, the page description can also be overridden on a per-document basis with custom front matter:

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

# Document title
...

This will set the meta tag containing the site description inside the document head for the current page to the provided value.

Adding a web app manifest¶

A web app manifest is a simple JSON file that specifies how your web application should behave when installed on the user's mobile device or desktop, which can be set via mkdocs.yml:

extra:
  manifest: manifest.webmanifest

Customization¶

Displaying the metadata¶

Sometimes it's useful to be able to display the medatada in the page body, e.g. print the name of the page author at the bottom of the page. To achieve that, you can extend the theme by adding the following contents to main.html:

{% extends "base.html" %}

{% block content %}
  {{ super() }}
  {% if page and page.meta and page.meta.author %}
    <p><small>Author: {{ page.meta.author }}</small></p>
  {% endif %}
{% endblock %}

Custom meta tags¶

on all pages¶

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

{% extends "base.html" %}

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

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 property="robots" content="{{ page.meta.robots }}" />
  {% else %}
    <meta property="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.

Social meta tags¶

Some further examples, including Open Graph and Twitter Cards:

{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.meta and page.meta.title %}
    {% set title = title ~ " - " ~ page.meta.title %}
  {% elif page and page.title and not page.is_homepage %}
    {% set title = title ~ " - " ~ page.title | striptags %}
  {% endif %}
  <meta property="og:type" content="website" />
  <meta property="og:title" content="{{ title }}" />
  <meta property="og:description" content="{{ config.site_description }}" />
  <meta property="og:url" content="{{ page.canonical_url }}" />
  <meta property="og:image" content="<url>" />
  <meta property="og:image:type" content="image/png" />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
{% endblock %}

{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.meta and page.meta.title %}
    {% set title = title ~ " - " ~ page.meta.title %}
  {% elif page and page.title and not page.is_homepage %}
    {% set title = title ~ " - " ~ page.title | striptags %}
  {% endif %}
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:site" content="<username>" />
  <meta name="twitter:creator" content="<username>" />
  <meta name="twitter:title" content="{{ title }}" />
  <meta name="twitter:description" content="{{ config.site_description }}" />
  <meta name="twitter:image" content="<url>" />
{% endblock %}