Setting up the meta plugin¶

Introduction¶

As you can see on the left - side menu, this plugin is placed as the first one. It is because this plugin can be considered as one that influences the way, you will be writing a documentation. So, why it's so essential?

There are a few reasons:

1. Automatic navigation building based on file and directory names. This simplifies a process of a document navigation creation in mkdocs.yml file, described in official documentation.
2. Based on file meta-data, you can set document:
   • URL,
   • creation/update date,
   • document publication state,
   • and some other less important. Most of these options, influence the SEO of the page build using MkDocs.

Probably you are now wondering why 2 quite different functionalities are placed in one plugin?

The answer is not so obvious and a bit technical, but in bigger simplification, it's way simpler and less complex to bound those functionalities together. The main reason for that is how MkDocs internals work. For example, when navigation is built and when final HTML files are generated. Other example could be a document status implementation that influences navigation building, file list creation and sitemap.xml creation. This process should be considered as one functionality and splitting it over 2 separate plugins is possible, but it will not only increase code complexity, but also will increase significantly complexity of configuration since many settings used for automatic navigation building are the same for defining file meta-data. So, if we split functionality into 2 separate plugins, the final user (You) will have to maintain consistency in mkdocs.yml file. With a single plugin approach, we can reduce this problem to just maintaining a single point of configuration and settings validation.

Meta-data¶

Markdown documents can contain additional metadata that is not rendered by MkDocs. This metadata is located at the beginning of the file (more information about this you can found in MkDocs documentation in Meta-Data section).

MkDocs supports 2 main formats of meta-data:

---
title: Your document title
description: A short description of document content that encourage to read it
---

This is the first paragraph of the document.

Title: Your document title
Description: A short description of document content that encourage to read it

This is the first paragraph of the document.

Document meta-data¶

As described in the previous section, you can provide additional meta-data that is unique for that document, and can change some behavior of the meta plugin, but not only. Some other MkDocs plugins also utilize these types of settings. One of the plugins is pub-blogor plugins included in Material for MkDocs.

Directory meta-data¶

The same approach can be taken for setting this up in the case of directories. To provide meta-data values, you have to create a file README.md inside the given directory and put the values accepted by this plugin. A list of possible settings can be found below.

Dates¶

In the metadata, there is a possibility to add two values related to dates.

---
date: 2023-05-19 15:40:36
---

---
update: 2023-06-12 14:16:52
---

Navigation automatic generation¶

In short, navigation automatic generation works based on alphabetical order of files and directories. If you are using any IDE (like PyCharm, VsCode or Obsidian) for documents creation and editing, the way of file order you see by default in the project or file browser of the tool, is the order of the files in navigation. Probably the easiest way of file ordering is to provide some prefix with the digits (take a look at this documentation repository for better understanding). The main problem with this approach would be strange names in file URLs and documentation titles on the web page. To solve that problems, the meta plugin uses two meta-data values that are common for document files and directories:

---
title: Document title
---

---
slug: document-slug
---

Document publication status¶

One of the functions provided by the meta plugin is a possibility to set document publication status. Each publication status has some implications for navigation building and links creation.

---
publish: true
---

---
publish: hidden
---

---
publish: false
---

Directory publication status¶

Publication status can also be set for whole directories. This gives you a control over the whole set of documents that are placed in given directories. Each publication status has some implications for navigation building and links creation.

---
publish: true
---

---
publish: hidden
---

---
publish: false
---

External links and redirections¶

Occasionally, you have a need to put a link to some external web page from the menu or just move one of your documents to other places in directory structure, but because of SEO it's good to put a redirection to that document from an old location. MkDocs offers you a way to put a link to an external web page but to make a redirection, you need to use an external plugin. The biggest problem with both things is that you need to edit mkdocs.yml file and this plugin is incompatible with WikiLinks etc. This is the reason why the meta plugin supports this functionality. There are 2 different ways to use redirections, and they work the same both for internal documentation files and external links.

External links¶

Sometimes you may want to create a link to the external page right in one of the menus instead of a link to some specific documents you have created.

Let's consider the below directory structure:

.
└─ docs/
      ├─ 01_home.md
      ├─ 02_contact.md
      └─ 03_my_company_link.md

03_my_company_link.md is the file you want to be the link to your company web page. You have 2 options doing it:

---
redirect: https://my_company.com/
---

---
redirect: true
---
[Link](https://my_company.com/)

As you can see, the first option (one with line path inside metadata) is much simpler.

Redirections¶

Sometimes you may want to move a document to a new directory but also preserve the original URL. This scenario is quite often when you share the link to your page over social media, and you cannot edit all the places, where the link was published. So, how to set up the redirection?

Let's consider the below directory structure:

.
└─ docs/
       ├─ archive/
       │    └─ redirected_to.md
       └─ articles/
              └─ redirected_from.md

archive/redirected_to.md is the file with the original content taken from articles/redirected_from.md file. Inside the file articles/redirected_from.md you have to enable redirection and put a link to the archive/redirected_to.md file. You have 2 options doing it:

---
redirect: ../archive/redirected_to.md
---

---
redirect: true
---
[Path](../archive/redirected_to.md){#dcea0642876d0caba61ad7244628a397}

As you can see, the first option (one with redirection path inside metadata) is much simpler, but the second one is easier to create in tools like Obsidian.

Slug¶

While documentation is generated, each of the file is converted from Markdown into HTML format. MkDocs preserves directories and file names, so the URL structure is the same as the Markdown structure. Quite often, this is not the best option for SEO and you may want to change it. To achieve it, you have to provide a slug meta-data value. You can provide it for both: files and directories.

Let's consider the below directory structure:

.
└─ docs/
       └─ 99_other/
              └─ 08_faq.md

This will produce this kind of URL:

https://yourdomain.com/99_other/08_faq/

It doesn't look good and is difficult to remember and not good in SEO perspective. To improve it, the above URL should look like this:

https://yourdomain.com/other/faq/

To make it happen, you have to use:

• README.md inside 99_other directory to change its URL to other,
• 08_faq.md to change its URL to faq.

.
└─ docs/
       └─ 99_other/
              ├─ README.md
              └─ 08_faq.md

---
slug: other
---

---
slug: faq
---

Generation mode¶

Slug can be generated based on one of the values:

• slug meta-data value,
• title meta-data value,
• directory or file name.

There are 3 slug generation modes that combine the above methods:

• title (default)
• filename

Below, you can see, a simplified algorithm of how slug is obtained.

flowchart TD
    START("start")
    SLUG("slug meta-data")
    TITLE("title meta-data")
    FILENAME("file name")
    END("end")

    START --> SLUG
    SLUG --> |set| END
    SLUG --> |title| TITLE
    TITLE --> FILENAME
    SLUG --> |filename| FILENAME
    TITLE --> |set| END
    FILENAME --> |set| END

Overview file¶

When using directory meta files, you mostly use its metadata for directory slugand directory publication status. But there is also a possibility to put some text to that file that, during a page generation, will produce a given directory index file. It means, that group of documents, can be described by a top-level document that can contain some sort of introduction, an overview or a summary. Take a look at the topic in Material for MkDocs navigation sections that describes how it looks like, and what theme features have to be enabled.

Configuration¶

To enable the built-in meta plugin, the following lines have to be added to mkdocs.yml file:

plugins:
  - pub-meta

General¶

plugins:
  - pub-meta:
      dir_meta_file: README.md

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Overview¶

plugins:
  - pub-meta:
      overview:
        enable: true
        default: auto
        key_name: slug

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Publication status¶

plugins:
  - pub-meta:
      publish:
        search_in_hidden: false
        search_in_draft: false
        file_default: draft
        file_warn_on_missing: true
        dir_default: published
        dir_warn_on_missing: false
        key_name: publish

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Redirect¶

plugins:
  - pub-meta:
      redirect:
        key_name: redirect

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Slug¶

plugins:
  - pub-meta:
      redirect:
        enable: true
        mode: title
        warn_on_missing: true
        key_name: slug

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Title¶

plugins:
  - pub-meta:
      title:
        key_name: title

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

Backlinks: