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-blog or 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
---

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.

Slug ¶

plugins:
  - pub-meta:
      slug:
        enable: true
        warn_on_missing: true
        key_name: status

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.

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: