A script to share your obsidian vault (in partial way) using mkdocs
Project description
PROJECT DOCUMENTATION
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
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.