Skip to content

Publisher for MkDocs

PyPI version License type PyPI Downloads last month Python versions GitHub last commit

Publisher for MkDocs is a set of plugins for MkDocs that was created originally as “yet another blogging plugin for MkDocs” (you can read more about this in this blog post ). During a process of development, I realized that it can become something more that will help not only me with blog creation, but also as a part of a wider publishing tool. Documents creation can be used with cooperation with an Obsidian.md that is a tool for creating a second brain and also an excellent Markdown files editor.

Currently, this plugin is also written with strict cooperation with Material for MkDocs theme. It was not tested on any, and probably some functionalities may not work as intended (for example, formatting of blog posts). However, all the plugins that are included in this package should work separately and not all of them have to be enabled (for example, pub-minifier will work with any other set of plugins).

Core concepts

Publisher for MkDocs is a set of plugins that was created with the below concepts:

User-friendly

The whole process of installation and configuration should be as simple as possible, so it's harder to get stuck just at the beginning of the way. Most of the settings are predefined the way, that the author of the documentation doesn't have to spend much time on configuration, etc. I know that some elements are still overly complicated, but the development process is not finished, so there is always a room for improvements. On the other hand, this tool will always be limited by the design of the tools that it's relay on. Usually, whenever possible, this tool should simplify the whole process of documentation publication.

Optimized for SEO

All the documents, if created with World Wide Web publication in mind, should be SEO optimized, so they are easier to find by any search engines. SEO it's not only about information that documents contain, but also with some more technical aspects like file size, interlinking, page load time, etc. All those aspects are quite technical one and not always taken into consideration when an author writes any piece of written text. For that reason, this tool is written the way, that the author doesn't have to think about some of those aspects. Some of the aspects are also described in this documentation as part of the documentation process creation.

Obsidian.md as first party editor

Obsidian.md is becoming the tool for creating Personal Knowledge Management (PKM) or a Second Brain . If you don't know this tool, but you are using any note-taking app like Notion, Evernote, etc. You should definitely try Obsidian. Why? It's because it allows you to achieve much more than any of the above tools and your notes are stored in Markdown files, so it's a great fit for MkDocs since both tools use this format. What's more interesting, Obsidian has lots of community plugins that allow you to achieve more, and some of them are also a great fit for documentation creation and allow you to speed up the process of writing it. This entire documentation was written using Obsidian with all Publisher for MkDocs plugins enabled. You are not forced to use Obsidian for editing, but its worth trying/

Included features

The list of most important features built into MkDocs Publisher: