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://fosstodon.org/@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

This is post 34 of 100, and is round 2 of the 100 Days To Offload challenge.

    • remove tag mkdocs
    • change topic
    • Change 100DaysToOffload message
    • Fix broken link

Comments

Reply via email