Faint graph paper grid background with black text of MkDocs

Add Custom Metadata to MkDocs

  • Adam Douglas

MkDocs only provides the ability to set metadata (key/value pairs) for title (document title) and template (template of page). Outside of this metadata can only be defined and set by passing to a page template. Therefore, if the MkDocs theme being used supports the desired metadata then they will be displayed on a page or control how the page is rendered. How this is done is determined by the theme’s configuration and built-in features. Thus, this means unless the theme being used supports the metadata, one must create or modify a theme in order to make use of metadata. The focus will be on modifying the theme that does not support the desired metadata, rather than creating a new theme.

What is Metadata?

A specific type of data that provides information for the associated primary data.

An example would be an email message, the message is the primary data, but the date and time it was sent or received is metadata. Another example of metadata for a website would be social media account links, authors of a post, etc.

Environment

Tested using the following…

Assumptions

  • General understanding of using a Linux terminal (command-line interface)
  • Steps prefixed with a “$” (dollar sign) represents the CLI (command-line interface) prompt
  • The text after the “$” is to be entered at the CLI
  • MkDocs is already installed and configured
  • The directory “project” represents the root of the website

Set Metadata for All Pages

The example below will add metadata to the HTML head element on all pages by using MkDocs overriding block to modify the theme. This method will not overwrite what is already present, and I will reference metadata set in the MkDocs configuration file, mkdocs.yml.

  1. Edit MkDocs configuration file

     $ nano project/mkdocs.yml
    
     theme:
         custom_dir: overrides
     extra:
         social:
             - icon: fontawesome/brands/mastodon
               link: https://mastodon.technology/@adamsdesk
               name: Adamsdesk on Mastodon
             - icon: fontawesome/brands/youtube
               link: https://www.youtube.com/channel/UCILZ-ICjQ5diK0kSmElfyXQ
               name: Adamsdesk YouTube
             - icon: fontawesome/brands/gitlab
               link: https://gitlab.com/adouglas
               name: Adam's Gitlab
    
  2. Create overrides directory

     $ mkdir project/overrides
    
  3. Create desired document to override

     $ nano project/overrides/main.html
    
     {% extends "base.html" %}
    
     {% block extrahead %}
         {{ super() }}
         {% for data in config.extra.social %}
                 <link rel="me" href="{{ data.link }}">
         {% endfor %}
     {% endblock %}
    
     extrahead               Add custom meta tags within the head element
     super()                 Load the original block content
     config.extra.social   References the Extra > Social settings within mkdocs.yml
    

Set Metadata Per Page

The example below will add metadata to the HTML head element per applicable pages by using MkDocs overriding block to modify the theme. This method will not overwrite what is already present, and I will reference metadata set in the page’s front matter if it exists, else it will use a default metadata.

  1. Edit MkDocs configuration file

     $ nano project/mkdocs.yml
    
     theme:
         custom_dir: overrides
    
  2. Create overrides directory

     $ mkdir project/overrides
    
  3. Create desired document to override

     $ nano project/overrides/main.html
    
     {% extends "base.html" %}
    
     {% block extrahead %}
         {{ super() }}
         {% 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 %}
    
     extrahead           Add custom meta tags within the head element
     super()             Load the original block content
     page.meta.robots    References the Page > Meta > Robots settings within a page
    

Set Metadata for an Entire Directory

The meta plugin comes with Material MkDocs and allows for setting front matter (metadata) per directory (folder). Doing so will set front matter for all pages found within the specified directory.

  1. Enable MkDocs Meta plugin

     $ nano project/mkdocs.yml
    
     plugins:
         - meta
    

    If desired, the default meta file name can be changed as follows.

     plugins:
         - meta:
             meta_file: '**/.metadata.yml'
    
  2. Create meta file

    The default meta files are named .meta.yml. Create one within a directory to apply metadata to all nested pages.

     $ nano project/docs/apps/.meta.yml
    

I’m publishing this as part of 100 Days To Offload. You can join in yourself by visiting 100DaysToOffload.com.