Skip to content

Setting up a blog plugin

Introduction

Publisher for MkDocs allows you to create a blog. A blog can be a sidecar for your current documentation, or it can be configured as a standalone. The entire blogging engine is created and preconfigured, so you can focus on content creation. It will handle creation of:

  • indexes,
  • archive,
  • categories,
  • tags,
  • pagination.

All the above documents are created outside docs directory, so they are not visible and do not interfere with your content.

This documentation contains a blogthat is created using this plugin, so you can take a look at a living example.

Date format

Currently, the date format of a blog posts is not configurable and has to look like this:

---

date: 2023-02-12 22:00:00

---

There is also a requirement, that each blog post, have to contain an unique date because without this, the algorithm responsible for posts display ordering (from newest to oldest) will not work correctly.

Slug

You need to provide a slug for every blog post. Without it, during a build, it will throw an unrecoverable error. It's going to be changed, so it will work the same as for Slug.

Configuration

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

plugins:
  - pub-blog

By default, the blogging plugin assumes that blog posts are located inside blog subdirectory. You have to create this directory manually, so the directory structure will look like this:

.
├─ docs/
│  └─ blog/
└─ mkdocs.yml

The last thing is to add a blog to a site navigation. There are 2 ways to do it:

When pub-metaplugin is configured and the directory for blog posts is set up, there is nothing more left to be configured. All the things related to creating a navigation section will be handled automatically by the pub-meta plugin.

If an existing pages are created in MkDocs, it's simple to just add a blog functionality. To achieve it, Any name with path to a blog subdirectory name (by default it's a blog) has to be added to the mkdocs.yml file and blogging engine will handle everything else.

nav:
  - ... # Previous navigation elements
  - Any name: blog
  - ... # Next navigation elements

Blog standalone mode

Standalone mode (blog as a starting page) was removed in version v0.6.0and now this is automatically detected, based on site navigation structure.

General

plugins:
  - pub-blog:
      teaser_marker: "<!-- more -->"
      searchable_non_posts: false
      posts_per_page: 5
      slug: blog

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.

teaser_marker

This option gives you an ability to split a blog posts that are a massive chunk of text into two parts: blog post teaser visible on blog posts index page and the full article. To split the blog post, you have to put a <!-- more --> in some line inside a content of your blog post. This value is a valid HTML comment, so it will not be rendered.

posts_per_page

When you gather over time some amount of blog posts, their index even with short teasers, they can take quite much space over a single page and scrolling down is not a convenient solution. To avoid this, blogging engine allows splitting index pages when they contain a certain amount of blog posts.

searchable_non_posts

This option controls the behavior of a search plugin for all dynamically created blog documents that are not blog posts. There is no need to make those pages visible, since all the text in those pages is a copy of the part of the blog post.

slug

This option gives you an ability to go to specify your blog direct URL, like https://yourblog.com/blog/. The blog part of the URL can be configured to a non-standard value.

Directories

This plugin to work correctly, needs to create and/or use some directories. Those settings should be considered as advanced and for day to day use, you should not change them.

plugins:
  - pub-blog:
      temp_dir: .pub_blog_temp
      archive_subdir: archive
      categories_subdir: categories
      tags_subdir: tags

Temporary directory is created at the same level as main docs directory and mkdocs.yml configuration file.

.
├─ .pub_blog_temp/
│  ├─ archive/
│  ├─ categories/
│  └─ tags/
├─ docs/
│  └─ blog/
└─ mkdocs.yml
temp_dir

Temporary directory is used by a blog engine to create an index files with a blog post teasers and other files like a list of archive, categories, and tags pages.

archive_subdir

Archive subdirectory is used to store dynamically generated documents that contain archive indexes.

categories_subdir

Categories subdirectory is used to store dynamically generated documents that contain categories indexes.

tags

Tags subdirectory is used to store dynamically generated documents that contain tags indexes.

Language

By default, the blogging plugin is set to use English (en) translation. Currently, available languages:

  • en - English,
  • pl - Polish.

To set up one of the above languages, the following line has to be added to the mkdocs.yml file:

plugin:
  - pub-blog:
      lang: "pl"

Translation

If there is no language that suits you best, you can translate part of the interface by providing values for the below keys inside the configuration mkdocs.yml files. Providing those values overrides values for setup of a given language, and this way it's possible to change only some of them.

Below, you can find a list of settings keys with English values that allow to translate some parts of the interface:

plugins:
  pub-blog:
    translation:
      teaser_link_text: Read more
      blog_page_title: Blog
      blog_navigation_name: Blog
      recent_blog_posts_navigation_name: Recent posts
      archive_page_title: Archive
      archive_navigation_name: Archive
      categories_page_title: Category
      categories_navigation_name: Categories
      tags_page_title: Tag
      tags_navigation_name: Tags
      newer_posts: Newer posts
      older_posts: Older posts

Backlinks:

Setting up meta

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 https://squidfunk.github.io/mkdocs-material/.

This defines a value for the document's creation date. It's also used by a blog pluginfor blog posts ordering and a meta plugin for updating a sitemap file.