Self hosted notes by using MkDocs (with blogging capability)

For last few months I was working on a project that started as tool for blog creators with Obsidian as a text editor. Main idea was to create a static site with blog, so it can be deployed anywhere (for example using GitHub Pages as a free hosting). At some point in time its functionality has expanded and at this stage (release v1.0.0 few days ago), can be considered as an alternative to official publish service with extra blogging capability. Whole project can be found here: <i class="fa-house fa-solid"> </i> - MkDocs Publisher

Currently, project supports:

  • wikilinks,
  • backlinks,
  • callouts,
  • charts (using obsidian-vega plugin).

Entire project is a bundle of self developed plugins for MkDosc and theme Material for MkDocs.

Before use, create a backup of you vault. This project creates some additional files for blogging capability that are removed after static files generation. They are in separate directory tree branch to main vault, so theoretically your vault is not touched, but it can be changed.

Additional general information:
Installation and configuration is for a person who is not afraid of some manual work and has basic Python knowledge. Documentation is at early stage, however all configuration options are described. If you consider it difficult, consider using official Obsidian Publish service.

Project documentation can be considered as a live demo of this project, since it was created using Obsidian and the project (vault is part of the project GitHub repository).

Feedback and ideas are highly appreciated.

PS. Project already has a backlog, but I’m open to new features ideas and issue reports: Backlog - MkDocs Publisher


Hi. It’s great to see another attempt for 3rd party publishing service.

I’m curious if u know the existence of plugin obsidian-github-publisher?

It’s a plugin for Obsidian that send note into a Github repo (via simple command in Obsidian) then automatically build and deploy using mkdocs-materials via Netlify/GithubPages/Vercel

I want to learn whether/how I can integrate your mkdocs-publisher package into it? Maybe a collaboration between you guys to make the best from both solutions.

The “backlinks” and “blog” part in your docs site looks neat. That’s what I want to use


Hi @bryan00,
I know this project and was looking into it before I started my, but to the point.
In general both project do very similar things, but have a different approach to building a static files:

  • obsidian-github-publisher - modify Markdown files before using MkDocs to build a page (it’s why there is an info in the project, not to use files from git pushed there by this plugin)
  • MkDocs Publisher - doesn’t modify original Markdown files (all links and other modifications are happening inside MkDocs plugins while building a static files, so you can store your vault in git repo and use it as a backup)

While it’s possible to use plugins from my project inside obsidian-github-publisher, but probably without deeper modifications either “backlinks” or “blog” will not work correctly, but …

My project can be used with cooperation of obsidian-git plugin and GitHub Actions, so final result would be automatic publishing notes/site in GitHub Pages on single Obsidian command, just git push. What’s more, obsidian-git can be configured to do automatic backups, so it could be fully automatic so you don’t have to use single command to have an automatic vault backup and publication. It’s already working on my private blog, but GitHub Actions workflow is not public. I will definetelly add documentation section how to do it (so far I was more focus on delivering functionality that complex documentation, there is already a section in the documentation where it was planned to be places)


Thanks for your insight on the difference between two approaches.

The possibility to use single command in collab with obsidian-git to publish automatically sounds promising.

Bookmarked your docs site to read more about the update related to the automation with github actions.

I really love the design principles here – especially the way you keep a clean separation between your vault content and the exported one, translating wiki links etc. without cluttering the vault.

I went through the docs and setup, and it all went smoothly. Will have to wait till the critical “how to publish” part of the docs gets fleshed out for the next steps . Looking forward to it!

Thank you for sharing.


I am the developer of GitHub Publisher and the linked template.

As you can see in the manifest.json, you are using the exact same “old” name for your project.

Using the same name can be confusing for both of us, so could you please consider changing the name of your project?

I understand that my project is not protected by any law or copyright, but I would like to maintain a recognizable name and avoid any confusion with your work, as our projects are quite different.

Although it is possible to use plugins from my project within obsidian-github-publisher, it is likely that features such as “backlinks” or “blog” may not function correctly without further modifications, but…

To be honest, I would like to test the blog and backlinks plugins that you have developed, as they could be valuable additions to my template. From what I have seen, there should be no issues with these plugins working alongside mine.

My project aims to enable publishing on various configurations, including Mkdocs (as my template is based on it), as well as Hugo and Jekyll. That’s why I initially chose a “generic” name. Perhaps I should consider changing it now. However, renaming the project could potentially confuse users, and I also have numerous repositories that would need to be renamed if I choose this option.

By the way, if you need to reach me, you can contact me on Discord (mara__li) or send me a private message in the forum.

Thank you.


Just short information for anybody who is interested in conflicting projects names. I have spoken some time ago with @Mara-Li about this on Discord, and we agreed that my project name will become a “Publisher for MkDocs” since this project is mainly developed for MkDocs and Obsidian integration is just a part of it, not a main functionality. Mara’s project is focused on delivering plugin for Obsidian (Github Publisher) with various backends (one of them is MkDocs). As mentioned in the above post, Mara is interested in reusing some of my functionality and for some time, I’ve been working on a new version that will address some issues, etc. We are cooperating in this area.
I hope that anybody who was concerned about this is a bit pleased;)
Also because of that, any new information regarding my project updates will be announced in a new topic with the proper project name, so it will not make any more or possible confusion.


Hey. I totally interested with ur project. maybe cross post here so that ppl interested would know :heart:

I will support the work of @Mara-Li but not sure what you are interested in. Our projects have a bit of different approaches to publication and design principles. My work is more like MkDocs first with the possibility to use Obsidian as an IDE/text editor and as an outcome it allows any user to publish their vault. Mara’s work is more like Obsidian first, with the possibility to use MkDocs as one of the tools to publish vault. If you are interested in anything specific, let me know, I will try to answer the question.

@Mara-Li can you add something to this conversation?