Skip to content

v1.0.0 - 2023-06-13

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:

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-obsidian plugin documentation.

I need to start to implement unit tests because this project becomes too big to test it manually and deliver production grade quality. Probably after introducing unit tests, I will end the beta period of this project and consider it as a production ready. It doesn't mean that the project will be complete or free from errors, but at least new releases should not break pages built with this project.

Also from now on all new releases will be smaller. I will try to focus on smaller improvements and fixes, so you should fell like this project is more alive.

Last thing is a new project logo:

MkDocs Publisher logo

Known Issues

List of known issues:

  • internal links in blog teasers are not working,

  • using icons in page title, will cause problems with title display in the browser window.



  • ❎ internal class for HTML modifications
  • ♻️ project license to MIT
  • ♻️ project cleanup
  • ♻️ internal method for importing other plugin config (needed for cross functionalities)

Auto-nav (plugin removed)

The whole functionality of this plugin has been moved to a new Meta plugin .


  • ❎ exclude from search blog posts teaser/index, category, tag or archive pages
  • ❎ exclude comments in blog posts teaser/index, category, tag or archive pages
  • ✅ internal links for blog posts teaser/index, category, tag or archive pages
  • 🚫 removed edit_url for blog teaser/index, category, tag or archive pages
  • ♻️ automatic detection of the blog as starting page (config value for this setting was removed)
  • ❎ post publication state (provided by Meta plugin )


  • ♻️ code refactor of HTML modification elements and logging added

Meta (new plugin)

This plugin is a Swiss army knife that helps a lot with various tasks related to publication, SEO, etc. Take a look at the below changelog to see what is offered by this plugin.

  • ❎ build navigation based on file names order
  • ❎ set multiple document parameters by using its metadata:
    • title - document title
    • slug - URL of the document
    • status - document publication status (published, hidden, draft)
    • date - document creation date
    • update - document last update date (used for sitemap and SEO optimizations)
  • ❎ directory metadata and additional settings can be set in a frontmatter of *.md file (default to ): - possibility to define slug (this affects only the directory where is placed)
    • possibility to define skip_dir (this affects only the directory and all subdirectories where the file is located)
    • possibility to define hidden_dir (this affects only the directory and all subdirectories where the file is located)
  • ❎ while serve page locally, all hidden and draft pages becomes published (this setting, helps with document preview while writing)

Obsidian (new plugin)

This plugin is a set of functionalities and should be split into various smaller plugins, but due to some cross functionalities, it has been integrated into the bigger one. Each sub plugin can be controlled separately, so if you don't need all the functionalities, you can just disable them or simply do not enable one that are disabled by default.


  • ❎ server watch can omit .obsidian directory that needs to be a part of the documentation directory that is automatically added into watch and causes server reload on (almost) any interaction with obsidian (changing settings etc.)
  • ❎ support for wiki links format for images and internal links
  • ❎ configurable image lazy loading option (SEO optimization)
  • ❎ documents and images file path solver (it doesn't affect documentation, but it's required by MkDocs for proper links generation)


  • ❎ mapping of all Obsidian callouts into Markdown admonitions
  • ❎ auto-generation of backlinks for all internal documents (visible as an custom admonition at the bottom of the page)
  • ❎ backlinks are not generated for blog temporary files like post indexes, archive, tags and categories
  • ❎ backlinks are grouped per page like in Obsidian (if more than one link is pointing from one page to another, all context links will be visible)



❎ - added ✅ - fixed ♻️️ - changed 🚫 - removed