Setting up a blog plugin ¶
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:
All the above documents are created outside
directory, so they are not visible and do not interfere with your content.
This documentation contains a blog that is created using this plugin, so you can take a look at a living example.
Currently, the date format of a blog posts is not configurable and has to look like this:
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.
To enable the built-in obsidian blog, the following lines have to be added to
The last thing is to add a blog to a site navigation. There are 2 ways to do it:
When pub-meta plugin 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,
with path to a blog subdirectory name (by default it's a
) has to be added to the
file and blogging engine will handle everything else.
Blog standalone mode
Standalone mode (blog as a starting page) was removed in version v0.6.0 and now this is automatically detected, based on site navigation structure.
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.
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.
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.
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.
This option gives you an ability to go to specify your blog direct URL, like
part of the URL can be configured to a non-standard value.
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.
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 subdirectory is used to store dynamically generated documents that contain archive indexes.
Categories subdirectory is used to store dynamically generated documents that contain categories indexes.
Tags subdirectory is used to store dynamically generated documents that contain tags indexes.
By default, the blogging plugin is set to use
) translation. Currently, available languages:
To set up one of the above languages, the following line has to be added to the
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
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