This release adds some more control over minifier plugin by adding the following settings:
cache_enabled- controls if cache is enabled both globally and per file type (cache is enabled by default),
exclude- list of files and/or directories that are excluded from minification both globally and per file type (by default list of exclusion is empty),
extensions- defines file extensions for each file type.
Exclusion file name pattern
setting allows defining exact match like
or by pattern like
. To match all subdirectories, you have to use
as a pattern, for example
Use it with caution, since using this pattern can be time-consuming (more information can be found at this link ).
The obsidian plugin, now supports:
- comments ,
- MathJax - right now you need to configure it manually , in the future it will be done automatically when this plugin is enabled,
- mixed type lists - right now you need to configure it manually , in the future it will be done automatically when this plugin is enabled.
I have also added some issue templates on project repository, so if you find some issue or have a future request, fell free to report a new issue .
This release is probably one of the most important ones for this project, but was also a bit problematic. You can ask why?
The biggest problem that I had, was about numbering this release. Because I wanted to bump all main dependencies (mainly Material for MkDocs ) i found that one of the metadata key names was colliding with Material for MkDocs and leading to unexpected behavior. I had to change it and for that reason, I was wondering how to handle this event. From one point of view, this is somehow braking change and I should create a v2.0.0, but didn't feel like this is release is big enough. It doesn't include any new functionality and is focused on bug fixes and internal improvements.
Publication status key rename
document or directory status metadata key has been renamed from
. This change solves 2 problems:
Conflict of the key name with Material for MkDocs .
Default name of the key is now the same as for Obsidian publish .
If you want to use old key name, you can do it by
changing key name
who is right now the most active user and tester of this project, I managed to fix all the problems with
(both wiki and Markdown syntax). There is much more to come in the area of Obsidian syntax support in the near future, like:
- comments - currently not supported,
- lists - supported partially (cannot mix ordered and unordered lists, etc.),
- page/note preview - currently not supported.
I will also create an entire section of the documentation related to Obsidian support (right now there is only a section on how to set it up ), so stay turned.
Some of you are still waiting for documentation about auto publication using GitHub Actions and some template repository, but it's under development and not yet (fully) ready. If you know how GitHub Actions works, you can take a look at this repository file deploy pages workflow . It's used for building this documentation that is pushed into docs branch after build. In the future, I'm planning to create a GitHub Action that will do all of it as a single step.
Also, there was a lot of happening in the project backstage, like new linter, added unit tests (partly code coverage) and some other small tweaks etc. A lot more things will come in upcoming releases.
Here I am with a new version of Publisher for MkDocs plugins. I have promised to make smaller releases, but my brain is refusing me to work on a small scale. It's really hard to achieve that, especially when I started to have some feedback from you, users of this tool. Because of that feedback and some problems you encountered, I decided to focus in this release on 2 main topics: some bug fixing and introducing a new plugin called pub-debugger . This plugin allows for an insight into all messages produced by plugins while building (or serving) a web page. Also, it's able to produce a ZIP file, with some basic information that could help me, whenever you will need to report an issue .
plugin do not send any files over the internet, but if you want to use a Zip file as an attachment for an issue submission or share it with anybody, please make a review of the content of this archive file.
It's your data and your responsibility what you are publishing over the internet. This plugin is only giving you the tool that should help, and you cannot blame me (the author of this plugin) for any potential data leaks.
There is also one very crucial topic related to this project name. When I shared information about Publisher for MkDocs over an official Obsidian.md community forum the developer of an Obsidian GitHub Publisher plugin provided me information that we have some conflict related to our plugins name. We were also spoken privately over Discord and came to some agreement related to our work. More information can be found in this thread , but in short:
- My set of MkDocs plugins will be called Publisher for MkDocs since my work is related to MkDocs with additional support for Obsidian as an IDE/text editor,
- Mara-Li Obsidian plugin will be called GitHub Publisher since her work is related to Obsidian with the possibility to use MkDocs as a beck-end for publication.
In the feature, some elements of this project could be part of Mara-Li work, but it's her decision. I will continue working on this project and help her with some potential issues solving.
I have also spent some time on unification of look the setup documentation. Previously, documentation was created a similar way as Material for MkDocs is doing it, but I decided to drop this approach and simplify it a little bit. Most of the work was around configuration options, that was too verbose. Currently, all configuration options related to given functionality are gathered in a single code block with their default values, so it's easier to copy it to yours
file. As a result, all descriptions related to those options are placed below this code block, so it's easy to find the information about it. I hope it's now easier to navigate and understand all the configuration options.
A lot of you have been asking me about comparison to other tools and I have answered to them in this Reddit thread . I have a plan to gather all this information and create a separate document about this (and also to some credits to projects I get inspiration from), but simply didn't have time for that so far.
There were also some requests related to the publication process. I'm aware that this is the biggest lacking right now of this project that is supposed to be related to publishing, and I will definitely solve this soon. There is an upcoming update related to that as:
- GitHub template repository,
- Docker image,
- GitHub Action,
I don't promise that all of the above will be ready in the next release, but some of them will be for sure.
This was quite a journey to make this release and push it to v1.0.0. So far, this whole documentation was created inside the Obsidian but since all the files are just a flat text file written using Markdown syntax , you were unable to see it. The reason for that was simple: integration with Obsidian was not "mature" enough to be presented. You can ask: "Why? Obsidian just uses the same Markdown syntax as MkDocs uses" . The answer to that is not so obvious. The simple answer is just "yes" , but the real answer is "not always" . Obsidian introduces some additional syntax options like callouts (equivalent to Markdown admonitions ) and WikiLinks for creating internal links. If you use them "as is" in MkDocs, you will see a pure (not parsed) text, not the intended one since MkDocs does not understand this syntax. To make it "understandable" for MkDocs, it has to be "translated" into regular Markdown syntax.
Translation is non-destructive
All markdown translations (or rather I should say conversions) are non-destructive to your Obsidian vault and occurs "on the fly" while static files are produced. It means that you can use this plugin side-by-side with Obsidian and use, for example, git repository as your vault backup. You don't have to copy or specially prepare your files before using this tool.
For that reason, a new plugin was created, that supports not only the mentioned Obsidian elements, but also some additional ones like:
- backlinks ,
- callouts ,
- wikilinks ,
- vega charts (using Vega Visualization Plugin for Obsidian ) - advanced solution for creating charts.
Material for MkDocs has its own social cards plugin , but there are some limitations of it (or rather I should say, their implementation is limiting in some areas). The Material approach to social cards is to generate an image based on document information and requires changing the template manually to add those cards.
Publisher for MkDocs uses a different approach to social cards:
- you can set an image per document, but you have to create this image by yourself - it gives you a better control over how it looks like, so it can be more create than the one generated from the template,
- you don't have to change a document template because all the data related to social cards is injected into HTML code of the document while rendering it.
If you need support for additional plugins, please make an issue with a future description.
For more details about this release, read more below or jump directly to pub-social plugin documentation.
It's a quick fix for a small problem in v0.4.0 .
In this release, many things have happened, but the most important one is a project rename.
During a development, many ideas about further development came to my mind. I have created a backlog .
This release was a quick fix for a wrong directory structure in
after package installation.
The main focus in this release is around making it a valid python package that can be published and to adding some additional functionalities around retrieving additional information from frontmatter.
Another blogging plugin for MkDocs? But why?
The simplest answer is: because I couldn't find one good enough (and free).
The flip side of the same coin was that I wanted to migrate my personal blog related to testing (sorry only in Polish, but you can try to use Google translator) from Nikola that works quite well, but sometimes is overly complicated, has almost none search functionality and markdown files are not the default one (but it's possible to use them). Why does the Markdown format is so important? Because I love Obsidian as a tool for gathering knowledge, and this format is a crucial part of that tool.
At the time when this plugin was created, there was no free and good alternatives. The only one that could be good enough was hidden behind a paid wall and was a part of a theme Material for MkDocs . Some of the ideas for this plugin and functionalities came from documentation of the Material for MkDocs theme, Nikola and other plugins.