Obsidian Mkdocs Publisher : A free publish alternative

[Mara-Li]

Hello !
I updated the plugin I made to support Obsidian Transclucy : mkdocs_embed_file_plugins

It nows support image and wikilinks in citation !

GitHub - Mara-Li/mkdocs_embed_file_plugins: A way to embed a file present in...

Normally, the requirements file doesn’t need to be updated, but I released two plugins to maintain them. You can use these requirements for your template :

mkdocs
mkdocs-material
mkdocs-mermaid2-plugin
mkdocs-ezlinked-plugin
mkdocs-awesome-pages-plugin
mdx_breakless_lists
mkdocs-preview-links-plugin
mkdocs-embed-file-plugins
Markdown

[tuancao]

@Mara-Li awesome tools with a lot of advanced feature .

I’m building something similar in NextJS framework but with very basic feature, would love to hear your feedback to help me go in the right direction!

Link is below here:

Alternative to Obsidian Publish (support wiki link style and folder navigation)

Hey guys, I’ve released this as open source. Check it out here: A Free & Open Source "Obsidian Publish" Alternative I’ve been looking for alternative to Obisidian Publish which would give me more freedom, and probably cheaper cost to maintain however most of the open source projects I found don’t support [[Wiki]] link style. So I set out to build my own solution. Below is a video demonstrating its functionalities. [Digital Garden Publish Demo] With Obisidian Help Vault …

Much appreciated!

[Mara-Li]

Hello !
I make a poll because, with Obsidian Callout & Admonition v8, I think about remove completely the support of admonition code blocks.
If a lot of user continue to use this functionality, I will don’t touch it (and don’t improve it).

In other case, I will make a breaking change update and encourage you to convert your admonition code blocks to callout with admonition plugin.

• Yes I continue to use Admonition code blocks
• No, I prefer to use callout

[Mara-Li]

Hey everyone ! I finally make it ! Yes. Obs2mk directly in Obsidian, without extrapush and… On mobile ! Yes.

But, how I done that, you ask ? With some Github Actions magic, a lot of caffeine, cry and a big ADHD hyperfocus.

So, how to give it a try ?

First, you need to create a template of the mkdocs template I created.
In a first step, you need to configure it. See here to know more about that.

And, if you have already cloned the template, please, add :

• The source folder and the .github-actions (see follow)
• The workflows
  You can also continue to use obs2mk as you do before. The two can be used in simultaneity.

Thereafter, you need to configure the .github-actions in the source folder. You must configure :

• The index key (for folder note citation)
• The default “category” key name
• The default folder to put the files.

Default is :

index_key=(i)
default_blog=notes
category_key=category

(Also check if you have the workflow for GitHub actions activated)

Now, you need to configure the plugin’s option. The plugin push in your repository and activate the ci workflow action, so you must configure :

• The repository’s name, the same you choose when building the template.
• Your github username
• A GitHub token to allow push. You can generate it here (you can set any expiration time).
• The share key (share) by default.
• The excluded folder : The plugin will never push the files in these folder, regardless of the share state.
• If you want to add a button to send file thought the file menu.

Normally, everything will work as expected! You can use the plugin to share multiple files, or just the opened one.

Some advertisements :

• No plugins can work (Dataview for example)
• The push can be very long on big vault.
• You need to have a proper tree structure with unique name file. No worry about the display in blog ; the title key in front matter will change it, so you can have a ezarezozre name and use a good title like reading book.
• I prefer to encourage you to use the shortlinks option in obsidian’s link option.
• No graph view
• The GitHub action will don’t move the file if you change the category key : you need to manually delete it to prevent duplicate.
• The folder note won’t be deleted in the repository (like, if you delete the folder or the note), you need to delete it manually.
• Empty folder will be deleted from GitHub.

A big, big thanks to @oleeskild for his digital garden plugin, where I take most of the code! Don’t forget to check it out.

Furthermore, it’s just a resume of the README of the plugin!

So, if you want to test, here is my baby :

GitHub - Mara-Li/obsidian-mkdocs-publisher: Making a plugin for obsidian to...

[Lise]

Mara-Li, thank you for all your work on this!
I tried implementing your system, but it was a tad too complicated for me because I don’t use Github. I was just wondering if your entire system depends on that, or if it is possible to by-pass it and go directly from the Obsidian Vault to a local server via all the scripts that do the work like translating wikilinks, etc?

[Mara-Li]

For the plugin workflow, it can only work with Github. But you could use completely a local server with the python workflow. You just need to use the --G option to prevent to push to git.

[Mara-Li]

Hello !
Some update for Publisher Plugin

• I added a new command to update the .github-actions settings using Obsidian. To do that, you just need to edit the settings in Obsidian and use the new command update settings workflow.
• You now have an option to add on file’s open, right click "share ".

I tried to implement the modal menu from Digital Garden but… It doesn’t work. I don’t have the skill for the moment :’). If anyone want to try, you can check the branch here.

[windily]

Crap, excellent solution, I’ve managed to build it. It’s really cool to generate a blog with one click, I’ll send it out when I do some beautification! Haha!

[Mara-Li]

Hello !
I’m so happy to announce that MKDOCS PUBLISHER is now on community plugins!

[Mara-Li]

Hello!

I updated the workflow and also the Mkdocs Callout and created Custom Tags Attributes.

If you want to use this solution “out of the box” you can now! You just need to copy the template, make your change, and push!
Note : You need to edit the mkdocs_build.yml in .workflow to remove the if: line. Also, don’t forget to disable the other files!

These file will be kept in the repo until I depreciate the entire things.

How to update your blog :

1. Delete the ci.yml and manual_run.yml, in .github/workflows
2. Update the mkdocs_build (or create a new one). Remove the if: at line 18
3. Update your requirements.txt with adding:

mkdocs-callouts==1.4.0
mkdocs-custom-tags-attributes==0.1.0

4. Delete the obs2mk line in requirements.

5. Update your mkdocs.yml. At the plugins part, add :

plugins:
  - callouts
  - custom-attributes:
       file: 'assets/css/custom_attributes.css'

(the file for custom-attributes is the file where you put the .hash and #custom attributes. You can change the path anywhere in your docs).

Note: Usually, you want to use the last version (because bug fix, shining function). I, here, fixed version in requirements.txt to optimize python cache. I created a workflow that check if any update exists for your requirements.

As the cache is shared between the GitHub actions, it will also update the requirements in cache.
It helps to speed up the build process.

Get the actions to update your requirements here

With that, the entire workflow take less than 1 min. Adding the GitHub page building, it takes ~1 min to build the blog.

[nhanjkl]

Have you done yet? I’m still looking for some inspiration so I’d be very much appreciated if you could share your blog so that I know what the end result will look like. I’m in process of looking around for the easiest way to publish my notes. I know nothing about coding so an easy to follow instruction is a must for me.

[Mara-Li]

Hello ! Yes, everything works great. I don’t plan to do refactor or big changement. But sometimes I do update for some bug or add little QoL function.

You can check my blog at : https://www.mara-li.fr/

[Mara-Li]

Hello!
I updated and fixed a bunch of things for custom tags attributes. The documentation is here : GitHub - Mara-Li/mkdocs-custom-tags-attributes: A mkdocs plugin to create custom attributes using hashtags

Also, i moved around some css files!

[Mara-Li]

Hello!
I updated some workflow and created a create_index.yml ! Now, you can create a blog list (with index) directly in GitHub.
To do that :

1. Go to the “Actions tab”
2. Click on “Index Creation”
3. Click on “Run Workflow”
4. Fill the form :
   • Folder name : The name of the folder you want to create, it will be the “new category”.
   • Parent folder : The optional path of the folder you want to create the new category in. For example, main_category/draft will create the docs/main_category/draft/folder_name folder.
   • Description : An optional category description.
   • You can also :
     • Hide the toc in the index file.
     • Hide the navigation panel in the index file.
     • Perform a dry-run : It will only show the result of the operation, but will not create the folder and the index file.

[Mara-Li]

Hello! Here is a little changelog this week! The update touch mainly the preview plugin. It not as better than Obsidian hover but i do my best.

This mkdoc’s plugin is now compatible with callouts and Custom tags attributes and you can configure how much text you can preview and the truncate character. To get this, update your mkdocs.yml as follow :

plugins:
	- search
	- tooltipster-links:
		callouts: true
		custom-attributes: 'assets/css/custom_attributes.css' #need to be the same file than the custom attribute plugin!
		max-characters: 400 #Use 0 or 1 for no limit
		truncate-characters: '...'		

I noted that the plugin doesn’t work with navigation.instant feature of Material Mkdocs, so don’t forget to remove it if you use it!

I also created some CSS for material to recreate something similary to Obsidian Hovering feature. Here the file

I also updated the Embed File plugins, and it now supports callouts and custom-attributes. Update your mkdocs.yml as follow :

plugins:
	- search
	- embed_file:
		custom-attributes: 'assets/css/custom_attributes.css'
		callouts: true

(Yeah, it’s a lot of repetition, i need to update the plugins to have a better configuration file, but I will stand with that for the moment huhu.)

I also updated the two plugins and the build will be faster!

[Mara-Li]

Hello everyone !
I updated the docs to add tutorial on how to use mkdocs with netlify !

Configuration

[Mara-Li]

Hello!

I think I will disable the preview file function (using the plugin mkdocs-preview-links-plugin) on the template, for the following error:

1. The plugin add a lot of build time because I need to register ALL file to the DOM.
2. Wrong data are displayed
3. Or no data displayed at all (randomly, without reason)
4. The “cut” of the file are not good and broke the DOM/HTML previewing.

I looking for someone that can code a Javascript code to replace it! It must be compatible with mkdocs and display the first paragraph/line of a note, including embed/image/callouts. Exactly as the Obsidian native publish hovering !

Please, DM me on discord (@Mara#3000) if you want to work on this !

[bestann]

I can’t deploy Gitlab Pages.
My files go to docs directory but tags.md is deleted. I get error:

0s
Run venv/bin/python3 -m mkdocs build
INFO    -  "highlightjs" feature is disabled in your plugin configuration.
INFO    -  "mermaid2" feature is disabled in your plugin configuration.
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/runner/work/blog/blog/site
ERROR   -  Tags file 'tags.md' does not exist.
Error: Process completed with exit code 1.

Do I need to enable Mermaid2? I found Diagrams - Material for MkDocs — native support for mermade

[Mara-Li]

Please, could you use the GitHub repository ?

[bestann]

I’m sorry, I use Github Pages GitHub - anutator/blog. I had to comment:

#- tags:
#    tags_file: tags.md

Besides I’ve found a mistake in overrides/partials/post-list.html:

{# page collection #}
{% set valid_pages=[] %}
{% for p in pages %}
    {% set pg = p.page %}
    {% if pg.meta and pg.meta.date %}
        {% set date = pg.meta.date | iso_time %}
        {% set _ = pg.__setattr__("date", date) %}
    {% elif page.meta.git_creation_date_localized_raw_iso_date %}
        {% set date = page.meta.git_creation_date_localized_raw_iso_date | iso_time %}
        {% set _ = pg.__setattr__('date', page.meta.git_creation_date_localized_raw_iso_date) %}
    {% else %}
        {% set date = build_date_utc | iso_time %}
        {% set _ = pg.__setattr__('date', date) %}
    {% endif %}

This variable shows the same date for all .md files:

page.meta.git_creation_date_localized_raw_iso_date

So I can’t get list of recent posts. You must change it to:

pg.meta.git_revision_date_localized_raw_iso_date

Besides my file was published when it had share: false, not only share: true.