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
TLDR
- Install / update with
pip install obs2mk --upgrade
- Template the blog, clone it and configure the blog.
- Configure the script (first run)
- Add
share: true
in Obsidian's note frontmatter - Customize the
category
key in Obsidian's note frontmatter - Run the script
obs2mk
Prerequisites
You need :
- Git and a Github Account
- Python
- Optional (Windows): Windows Terminal
Quick installation tutorial
- Click on use this template[^7]
- Use the name of your choice.
- Click on code → SSH ; Copy the link
- Run (in terminal):
git clone [[PASTE THE LINK HERE]] publish_blog
pip install obs2mk --upgrade
Creating the blog
Customization
In your new publish_blog
folder, you will spot a mkdocs.yml
. This file allows you to customize your blog! The most important to edit :
site_name
site_description
site_url
(critical) : By default, it'shttps://github_username.io/repo_name
[^8]
To edit the logo and the favicon, first put the chosen file in assets/logo
, and change logo
and favicon
:
logo: assets/logo/logo_name.png
favicon: assets/logo/favicon.png
You can customize :
- Font
- Color scheme, palette, icons
- Language
Check the documentation to get more information
You don't need to touch anything in features
; markdown_extensions…
Local testing (optional)
To run locally the blog, you need to install the requirements and run mkdocs serve
.
cd publish_blog
pip install -r requirements.txt
mkdocs serve
The blog will be published through GitHub Page using the gh-page
branch. Everything is already configured by the template for that.
Obs2mk : Obsidian to Mkdocs
The script's goal is to move an authorized file (or multiple authorized file) from your Obsidian's vault to your blog's repository. It will :
- Move linked image in
docs/assets/img
- Convert the code block Admonition to material Admonition[^1]
- Convert the Callout Syntax to material Admonition.
- Remove Obsidian's comments as
%% comments %%
- Copy the file in
docs
or a specific folder structure. - Add custom CSS based on markdown attribute or tags (CM6 Live Preview ; Markdown Attribute and Contextual Typography).
Furthermore, it will also carry :
- Of the support of Folder Note — Pagination Indexes
- Copy a link to the blog converted file (only if one file is converted)
File's front matter
The script relies on the front matter** of the notes you want to publish.
share: true
allow publishing the file[^2]category
to choose where the file will be after conversion ; allowing categorization for the blog.[^6]category: false
will hide the file from navigation.category: hidden
will do the same.category: folder1/folder2/
will move the file infolder2
, underfolder1
category: folder1/folder2/filename
will rename the fileindex
and allow support of section's index page
update: false
prevent to update the file after the first publicationdescription
: Add a description to the file (for meta-tag sharing)[^3]title
: Change the title in the navigation.image
: Add an image for meta-tags sharing.[^3] It needs to be the name of the file, asimage.png
.
Usage
The script can be use :
- Directly in Obsidian, using Obsidian Shell Commands (see Obsidian Shell's configuration)
- In Terminal.
The supported system are :
- macOS, Linux and Windows
- IOS (with Pyto and/or a-shell with Working Copy)
Configuration
At the first run, you will be asked to configure some key and specific path.
- Vault : Use the file dialog to choose your vault folder.
- Publish repository folder : As vault path, use the file dialog.
- share : You can change the
share
key. By default, it'sshare
- Index key: Support for citation of pagination index pages. By default, it uses
(i)
- Default blog folder: By default, the notes will be in
docs/notes
but you can change that, or use/
for root.
The file will be in site-packages/mkdocs_obsidian/.mkdocs_obsidian
(unless for Pyto : the .env
will be directly in site_package/.mkdocs_obsidian
)
Terminal
Global options :
--git
: No commit and push to git ;--mobile
: Use mobile shortcuts instead of--git
--meta
: Update frontmatter of source files--keep
: Don't delete files in blog folder--shell
: Remove Rich printing
Commands and specific options :
- config : (it will ignore
--use configuration_name
)--new configuration_name
: Create a specific configuration for some files
- all : Share all vault
--force
: Force updating (ignore the difference between the source and blog file)--vault
: Share all vault file, ignoring the share state.
file [file*]
: Share only one file
usage: __main__.py [-h] [--mobile | --git] [--meta] [--keep] [--use configuration_name] {config,all,file} ...
positional arguments:
{config,all,file}
config Configure the script : Add or edit your vault and blog absolute path, change some keys.
all Publish multiple files
file Publish only one file
options:
-h, --help show this help message and exit
--mobile, --shortcuts
Use mobile shortcuts, without push
--git, --g, --G No commit and no push to git
--meta, --m, --M Update the frontmatter of the source file, adding the note blog's link
--keep, --k, --K Keep deleted file from vault and removed shared file
--use configuration_name, --config configuration_name
Use a different config from default
The commands order is :
obs2mk (global_options) [all|config|file FILEPATH] (specific_options)
Where :
- Global and specific options are optional
all
,config
andfile
[^9] are required You can use the command without argument withobs2mk
to share everyshare: true
file in your vault.
Share one file : obs2mk file FILEPATH
It will :
- Update the
share
state in original file - Convert one file, regardless of what is the
share
state.
Share all file : obs2mk all
or obs2mk
You can share multiple documents at once with scanning your Vault, looking for the share: true
. It will convert automatically these files.
Only file with modification since the last sharing will be updated.
You can :
- Share entirely your vault (that's ignore the
share
state) with :obs2mk all --vault
- Ignore the difference between the source file and the blog's file with :
obs2mk all --force
Also, you can combine the two options.
Configuration
You can use and create multiple configuration files. This allows to have multiple site based on one vault, or different vault accross one site...
- To create a new configuration file :
obs2mk config --new configuration_name
- To use a configuration use :
--use configuration_name
For example :obs2mk --use configuration_name
Obsidian Shell Configuration
You could create :
- A command to publish everything : alias
Publish
withobs2mk --obsidian
- A command to publish one specific file : alias
Publish {{title}}
withobs2mk --obsidian file {{file_path:absolute}}
- Event shortcuts for file menu event :
Publish {{event_file_name}}
:obs2mk --obsidian file "{{event_file_path:absolute}}
- Folder Note event (folder menu event):
Publish {{event_folder_name}}
:obs2mk --obsidian file "{{event_folder_path:relative}}\{{event_folder_name}}.md"
You can create a button with :
IOS
The script support IOS using :
- a-shell (Free)
- Pyto ($3 lite version / $10 complete version) [^4]
- Working Copy (Free for student / $19)
The option
mobile
will never push. You need to use Working Copy to push the converted file.
You can :
- Share the entire vault :
obs2mk --mobile all --vault
- Share a specific file, using its name :
obs2mk --mobile file "filename"
.[^5] This option can be used especially with Shortcuts
Customization
- You can prevent the script to share file in specific folder, with editing
folder
list inexclude.yml
- You can prevent the script to delete some file with editing
file
list in the same file. - You can, also, create some CSS customization with hashtag, with editing
docs/assets/css/custom_attributes.css
. See Custom Attribute for some example.
Blog : Customization
Custom attribute example
You can create Inline Markdown Attribute using hashtags in Obsidian. For example, to align some text to right :
- Add
#right {
display: inline-block;
width: 100%;
text-align: right;
font-weight: normal;
}
- Add
#right
on the last part of a line :
Lorem ipsum dolor sit amet, consectetur adipiscing elit. In mollis, libero porttitor gravida accumsan, justo metus pulvinar nulla, vitae dictum odio ligula non nisl. Vivamus id venenatis nulla. Nullam sed euismod ligula. Pellentesque tempor elit felis, lobortis vulputate risus gravida et. Curabitur auctor sed libero nec consectetur. Nam placerat rhoncus risus, euismod sagittis eros bibendum ac. Maecenas tellus libero, porttitor ac purus sit amet, viverra suscipit dolor. Proin id nisl velit. Ut at tincidunt libero, ac pharetra mi. Integer non luctus nisi. #right
It will appear as:
Folder note
You can create a folder note if you use a category
front matter key that have the last folder with the same name as the file. For example :
category: folder1/folder2/filename
. The file filename
will be renamed index
and the folder will be named filename
.
To support the citation and link to these page, you need to use an index key (cf configuration).
Some examples of citation and their transformation :
In Obsidian | In Publish |
---|---|
[[Real File|(i) Alias]] |
[[index|Alias]] |
[[Real File|(i)]] |
[[index|Real File]] |
[(i) Alias](Real file) |
[Alias](index) |
[(i)](real file) |
[real file](index) |
Admonition & callout customizable
The script support custom admonition. For that, you first need to edit custom_attributes with adding the support, as follow in Admonition's docs.
For example, to add a dictionnary
admonition:
:root {
--md-admonition-icon--dictionnary: url('data:image/svg+xml;charset=utf-8, <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 22a2 2 0 0 0 2-2V4a2 2 0 0 0-2-2h-6v7L9.5 7.5 7 9V2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12z"/></svg>')
}
.md-typeset .admonition.dictionnary,
.md-typeset details.dictionnary {
border-color: rgb(43, 155, 70);
}
.md-typeset .dictionnary > .admonition-title,
.md-typeset .dictionnary > .summary {
background-color: rgba(43, 155, 70, 0.1);
border-color: rgb(43, 155, 70);
}
.md-typeset .dictionnary > .admonition-title::before,
.md-typeset .dictionnary > summary::before {
background-color: rgb(43, 155, 70);
-webkit-mask-image: var(--md-admonition-icon--dictionnary);
mask-image: var(--md-admonition-icon--dictionnary);
It will give you :
The dictionnary
will be recognized, and converted !
Obsidian
Some useful plugin to support the script :
- Metacopy
- Obsidian Shell (cf Obsidian Shell)
- Customizable Sidebar
- Obsidian Customizable Menu
- Alx Folder Note
- Custom Attribute :
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 activate metacopy only for share: true
. Metacopy also support the folder note.
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!
Front matter template
title:
share:
description:
category:
Limitation
- The plugin rely a lot on filename, without regarding the folder. Please use unique naming and use the
title
key if you need to. - The plugin will not delete the
index
files (cf Folder Note) - The script can be long on big vault.
- The script will not manually move the file if you change a
category
: you need to delete it manually to prevent duplicate. - ⚠️You must use
shortlinks
in Obsidian configuration.
If you have more question, don't forget to read the Q&A !
[^1]: No support for nested admonition
[^2]: This key can be configured
[^3]: Meta tags are snippets of text that describe a page’s content; the meta tags don’t appear on the page itself, but only in the page’s source code. Meta tags are essentially little content descriptors that help tell search engines what a web page is about. Source
[^4]: Using Pyto you need to add the writing authorization for your vault and blog repository. You can access it in parameters > Runtime.
[^5]: Beware, if it exists a file with the same name, it will take the first found.
[^6]: You can customize the folder with Awesome Pages
[^7]: You must be connected to copy the template ! You can test locally through clone > https : git clone https://github.com/Mara-Li/mkdocs_obsidian_template.git
or with downloading the ZIP
[^8]: You can found the link in Repository settings > Pages.
[^9]: For file
you need to add the filepath of the file you want to share : obs2mk (global_option) file "filepath" (specific_options)
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.