A script to share your obsidian vault (in partial way) using mkdocs
Project description
Mkdocs Obsidian
Mkdocs Obsidian is an association between a python script and a Material mkdocs template to get a personal wiki site based on your Obsidian Vault.
Owlly Seed (My Blog ; In French)
Screenshot
Pre-requiries
Requirements
-
Python and Pip
-
Mkdocs :
pip install mkdocs
-
Material Mkdocs using
pip install mkdocs-material
-
Mermaid2 with
pip install mkdocs-mermaid2-plugin
. -
Roamlinks :
pip install mkdocs-roamlinks-plugin
-
mkdocs-obsidian :
pip install obs2mk
-
mkdocs-awesome-pages :
pip install mkdocs-awesome-pages-plugin
You can install all package with pip install -r requirements.txt
Get started
First, create the template in GitHub and download it with git
(as git clone git@github.com:your_username/blog_name.git
)
Customization
To make it your, you need to change, in mkdocs.yml
site_name
,site_description
site_url
- The logo and favicons
- If you want, the palette, use color scheme from material and edit
scheme
andaccent
.
The material's theme includes a lot of parameters and personalization, so don't forget to check to make the site yours! Also, there is a hundred of plug-ins (“extension”) for mkdocs so don't hesitate to give an eye! You will find a lot here.
To try your site without online, use mkdocs serve
.
You can publish your website using Github Page using the gh-page
branch. This branch is pulled by the .workflow
file, so don't worry about it.
Now you have two choices : move the file you want in docs
(and the subfolder you want) or you can use Mkdocs_Obsidian
.
Obsidian compatibility
So, with the configuration I have done, the mkdocs support :
- Folder note : the file need to be named “index” (instead of the name of the folder)
- Admonition
- Wikilinks and relative links
- Highlight and tilde markdown
- Mathjax and Mermaid
- Embed (citation) files (entire file, inline, heading)
- Custom Attribute, as CM6 Attribute (with tags), Markdown Attribute and Contextual Typography (with tags).
Mkdocs Obsidian
Utilities and interest
A vast party of the script is taken from my previous project, YAFPA
The script will care about some things you can forget :
- Moving your image in assets ;
- Change the admonition from the plugin to material admonition (mainly for codeblocks)
- Remove Obsidian comment (
%% text %%
) - Create a folder structure based on the
category
key. Without it, the note will be created indocs/notes
.
If you use the --meta
option, it will also add, in the original file a link to the blog.
⚠️ If the script crash for any reason at the moment where the script updates the frontmatter, you can lose some file.
Usage
usage: obs2mk [-h] [--git | --mobile] [--meta] [--keep] [--config] [--force] [--filepath FILEPATH | --ignore]
Create file in docs and relative folder, move image in assets, convert admonition code_blocks, add links and push.
options:
-h, --help show this help message and exit
--git, --g, --G No commit and no push to git
--mobile, --shortcuts, --s, --S
Use mobile shortcuts fonction without push.
--meta, --m, --M Update the frontmatter with link
--keep, --k, --K Keep deleted file from vault and removed shared file
--config, --c, --C Edit the config file
--force, --d, --D Force conversion - only work if path not specified
--filepath FILEPATH, --f FILEPATH
Filepath of the file you want to convert
--ignore, --ignore-share, --no-share, --i, --vault
Convert the entire vault without relying on share state.
At the first start of the script, it will ask you :
- The absolute path of your vault and blog in your PC.
- The key you want to use to share the file (default :
share
).
This file will be in your site_package/mkdocs_obsidian
folder.
On pyto, it will be directly in site_package
You can reconfigure the option with obs2mk --config
.
By default, the script will remove all file that doesn't exist in the vault, and file where you remove the share (share: false
, or removed the key). You can keep all these file with --k
. Empty folder will be also removed in this process.
A little note about "Folder Note": If the file has the same name as the last part of
category
, it will be renamedindex
during conversion.
However, this prevents the file from being deleted if its source is deleted from your vault: in this case, you have to delete it manually.
⚠️ You need to configure and use an alias to cite an index file ; By default, this alias is
(i)
but it can be configured in environment configuration. Some example :[[Real file|(i) Alias]]
→[[index|Alias]]
|[[Real File|(i)]]
→[[index|Real file]]
Git Note : If a folder is empty, it will be "erased" in git.
Share one file
To share only one file : obs2mk --f FILEPATH
. It will :
- Update the state status in original file (
share: true
) - Re-write the file if exist or create it in the folder you put in
category
This option will pull the file, regardless of what is theshare
state.
Share “all” files
You can share multiple documents using the share: true
key, in frontmatter. The script will scan your entire vault and automatically convert the file with this key.
There is two options :
- By default, the script will compare with the older version and write only if changement are detected, based on the content of the file and the last modified time.
- Using
--force
will force the re-writing.
You can force to skip the update with update: false
in the frontmatter : the file, no matter what, will not be updated.
Share the entire vault
Using the command --ignore
will ignore the share
state : you can share your entire vault using that, whatever the state is. By default, it will not overwrite file already exist (and not different), so the --force
option can also be used.
usage: obs2mk [-h] [--git | --mobile] [--meta] [--keep] [--config] [--force] [--ignore]
Mobile
Read more
The mobile option is similar to the git
option but with some nuance. When used to publish a single file, you can use only the file name, without the path.
:warning: Be careful though, in case you have several files with the same name, the script will take the first file found.
This option can be used especially with the "Shortcuts" application on IOS, to share a file directly from the share sheet.
One file usage : obs2mk --mobile --f "filename"
All file usage : obs2mk --mobile
Mobile supports all previous option, including --ignore
.
IOS
Using :
- a-shell (Free)
- pyto (3$ lite version / 10$ complete version)
- Working Copy (Free for student / 19$)
You can update your blog.
The script will rely on some a-shell or pyto command to help you to build the environment, so you don't need to edit manually the file in case of you change your folder. Also, on IOS, get a path manually is a mess so...
:warning: For pyto, you need to add the writing autorization for your vault folder and blog repo folder.
You can access to it in parameters > Runtime > Accessive folder
After, you can use the same option as on a PC.
Customization
There are some files to customize the script :
- You can create custom admonition with material docs and adding the name in
custom_admonition.yml
. - You can completely exclude some folder of your vault with
exclude_folder.yml
. You can exclude specific path asfolder1/subfolderA
etc. - Using the
\docs\assets\css\custom_attributes.css
you can create specific aspect for your tags, and it also adds compatibility with CM6 Attribute and Contextual Typography.
Limitation
- Nested admonition doesn't work for the moment. I don't use it a lot, but if you want, you could improve the script or create a mkdocs plugin to care of that.
- The script will not delete the file and folder if you change the
category
key. Beware of this. - Share “all” can be long on big vault.
- File with same name can have some problem while scanning because I don't keep your folder structure. Please, beware of this! Don't forget, you can use
title
if you want a specific name (and this name already exist).
Support
The script can work on any platform that support python. The script doesn't use Cpython, so don't worry about it for IOS.
Obsidian
→ Please use Wikilinks with “short links” (I BEG YOU)
You can integrate the script within obsidian using the nice plugin Obsidian ShellCommands.
You could create two commands :
- Publish everything: Alias
Publish
withobs2mk --obsidian
- Publish one specific file : Alias
Publish {{title}}
withobs2mk --obsidian --f {{file_path:absolute}}
With the 0.10
you could also add event shortcuts :
- File menu event
Publish {{event_file_name}}
:obs2mk --obsidian --f "{{event_file_path:absolute}}"
- Folder Note event
Publish {{event_folder_name}}
:obs2mk --obsidian --f "{{event_folder_path:relative}}\{{event_folder_name}}.md"
You can use :
- Customizable Sidebar
- Obsidian Customizable Menu
To have a button to share your file directly in Obsidian !
Metacopy
Using metacopy you can quickly copy a link to a shared page, without using this option (so, yes, the script does not edit your source file !). To create a link, you need to configure :
category
inkey
- Add your
set_url
inbase link
- Add
category
inkey link
Also, you can remove the metacopy from your file menu using a key, so you can active metacopy only for share: true
. Metacopy support also the paginations.index
.
The final configuration of metacopy for mkdocs_obsidian will be :
So, in the end, a menu will appear on file with share: true
and a category
configured. This menu is on the left click and the file-menu. You can quickly copy a link from there, like a google or notion sharing link !
Frontmatter and option
Script
The script need one key, to share the file. You can configure the key in the configuration of the script.
If you want a folder structure in docs
, you need to use the category
keys, with the form of path/path
. You can also block a file to update with update: false
.
Note : With awesome-pages you can hide folder from navigation. To hide a file, just use hidden
in category
(as category: hidden
). Links, image will work without problem.
You also can use category: false
to use the hidden folder.
PS: Awesome Pages allow a lot of configuration for folder, as file order ! Don't forget to check it out !
Mkdocs
Material give you the possibility to add SEO tags with :
description
title
(will change also the title in the navigation)image
: Add an image (don't forget the format) / Need to be a relative link.
Template
So, the final frontmatter template is :
---
title:
share:
description:
category:
---
If you have more question, don't forget to read the Q&A !
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.