Mkdocs obsidian publish - Publish your obsidian vault through a python script

Overview

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.

Mkdocs Obsidian Template

Owlly Seed (My Blog ; In French)

Screenshot

image_1 ![image_2(screenshot/image_2.png) image_3 image_4

Pre-requiries

You can install all package with pip install -r requirements.txt

Get started

First, copy the template in GitHub. 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 and accent.

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 :

I didn't found a way to embed file with wiki links for the moment. Because of the strange behavior of roam links, these embedded file will be rendered as image. The script will care of this bug.

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 in docs/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.

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 :

  1. category in key
  2. Add your set_url in base link
  3. Add category in key 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 !

Here is a demo : click to get a video !

Usage

usage: obs2mk [-h] [--git] [--meta] [--keep] [--config] [--force | --filepath FILEPATH]

Create file in docs and relative folder, move image in assets, convert admonition code_blocks, add links and push.

optional arguments:
  -h, --help            show this help message and exit
  --git, --g, --G       No commit and no push to git
  --meta, --m, --M      Update the frontmatter
  --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

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 folder.

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.

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 the share 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.
  • Using --force will force the re-writing.

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 as folder1/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).
  • Bloc citation doesn't work, the script will care of that.
  • Embed file (citation and # too) doesn't work, the script will also care about it !

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.

IOS

Using :

First, in a-shell, run pickFolder and choose the folder of your vault, and rerun pickFolder to choose the folder where are the blog data (you need to clone with Working Copy) After, do showmarks and copy the two path in any note app. Check if the path is not broken because of the paste! You can also do :

cd 
showmarks > bookmark
vim bookmark

Here is a blank sheet to help you if you want to manually write / edit it :

vault=
blog_path=
blog=
share=

With :

  • vault: Vault Absolute Path
  • blog_path : Blog repository absolute path
  • blog : Blog link (same as site_url from mkdocs.yml)
  • share : your wanted share key ; by default : share

Before running the shortcuts, you need to install all requirements, aka :

pip install obs2mk
obs2mk --config

After, in a-shell, you can use the same option as on a PC.

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 :

  1. share all : obs2mk
  2. share one : obs2mk --f {{file_path:absolute}}

You can use :

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.

Mkdocs

Material give you the possibility to add SEO tags with :

  • description
  • title (will change too 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:
---
You might also like...
Plugins for MkDocs.
Plugins for MkDocs.

Plugins for MkDocs and Python Markdown pip install neoteroi-mkdocs This package includes the following plugins and extensions: Name Description Type m

Resource hub for Obsidian resources.

Obsidian Community Vault Welcome! This is an experimental vault that is maintained by the Obsidian community. For best results we recommend downloadin

This tutorial will guide you through the process of self-hosting Polygon

Hosting guide This tutorial will guide you through the process of self-hosting Polygon Before starting Make sure you have the following tools installe

Python script to generate Vale linting rules from word usage guidance in the Red Hat Supplementary Style Guide

ssg-vale-rules-gen Python script to generate Vale linting rules from word usage guidance in the Red Hat Supplementary Style Guide. These rules are use

An open-source script written in python just for fun

Owersite Owersite is an open-source script written in python just for fun. It do

Loudchecker - Python script to check files for earrape

loudchecker python script to check files for earrape automatically installs depe

EasyMultiClipboard - Python script written to handle more than 1 string in clipboard

EasyMultiClipboard - Python script written to handle more than 1 string in clipboard

A collection of simple python mini projects to enhance your python skills

A collection of simple python mini projects to enhance your python skills

Valentine-with-Python - A Python program generates an animation of a heart with cool texts of your loved one
Valentine-with-Python - A Python program generates an animation of a heart with cool texts of your loved one

Valentine with Python Valentines with Python is a mini fun project I have coded.

Comments
Releases(v4.0.1)
Owner
Mara
Student in Master 2 : Biology, epidemiology and risk gestion. I love roleplay and shitposting. I love conding in python and love learn new things !
Mara
Python syntax highlighted Markdown doctest.

phmdoctest 1.3.0 Introduction Python syntax highlighted Markdown doctest Command line program and Python library to test Python syntax highlighted cod

Mark Taylor 16 Aug 09, 2022
The mitosheet package, trymito.io, and other public Mito code.

Mito Monorepo Mito is a spreadsheet that lives inside your JupyterLab notebooks. It allows you to edit Pandas dataframes like an Excel file, and gener

Mito 1.4k Dec 31, 2022
Poetry plugin to export the dependencies to various formats

Poetry export plugin This package is a plugin that allows the export of locked packages to various formats. Note: For now, only the requirements.txt f

Poetry 90 Jan 05, 2023
A set of Python libraries that assist in calling the SoftLayer API.

SoftLayer API Python Client This library provides a simple Python client to interact with SoftLayer's XML-RPC API. A command-line interface is also in

SoftLayer 155 Sep 20, 2022
A simple flask application to collect annotations for the Turing Change Point Dataset, a benchmark dataset for change point detection algorithms

AnnotateChange Welcome to the repository of the "AnnotateChange" application. This application was created to collect annotations of time series data

The Alan Turing Institute 16 Jul 21, 2022
Leetcode Practice

LeetCode Practice Description This is my LeetCode Practice. Visit LeetCode Website for detailed question description. The code in this repository has

Leo Hsieh 75 Dec 27, 2022
API spec validator and OpenAPI document generator for Python web frameworks.

API spec validator and OpenAPI document generator for Python web frameworks.

1001001 249 Dec 22, 2022
Quick tutorial on orchest.io that shows how to build multiple deep learning models on your data with a single line of code using python

Deep AutoViML Pipeline for orchest.io Quickstart Build Deep Learning models with a single line of code: deep_autoviml Deep AutoViML helps you build te

Ram Seshadri 6 Oct 02, 2022
This is the repository that includes the code material for the ESweek 2021 for the Education Class Lecture A3 "Learn to Drive (and Race!) Autonomous Vehicles"

ESweek2021_educationclassA3 This is the repository that includes the code material for the ESweek 2021 for the Education Class Lecture A3 "Learn to Dr

F1TENTH Autonomous Racing Community 29 Dec 06, 2022
This is a template (starter kit) for writing Maturity Work with Sphinx / LaTeX at Collège du Sud

sphinx-tm-template Ce dépôt est un template de base utilisable pour écrire ton travail de maturité dans le séminaire d'informatique du Collège du Sud.

6 Dec 22, 2022
A Python package develop for transportation spatio-temporal big data processing, analysis and visualization.

English 中文版 TransBigData Introduction TransBigData is a Python package developed for transportation spatio-temporal big data processing, analysis and

Qing Yu 251 Jan 03, 2023
A system for Python that generates static type annotations by collecting runtime types

MonkeyType MonkeyType collects runtime types of function arguments and return values, and can automatically generate stub files or even add draft type

Instagram 4.1k Jan 07, 2023
Bring RGB to life in Neovim

Bring RGB to life in Neovim Change your RGB devices' color depending on Neovim's mode. Fast and asynchronous plugin to live your vim-life to the fulle

Antoine 40 Oct 27, 2022
Xanadu Quantum Codebook is an experimental, exercise-based introduction to quantum computing using PennyLane.

Xanadu Quantum Codebook The Xanadu Quantum Codebook is an experimental, exercise-based introduction to quantum computing using PennyLane. This reposit

Xanadu 43 Dec 09, 2022
This repo provides a package to automatically select a random seed based on ancient Chinese Xuanxue

🤞 Random Luck Deep learning is acturally the alchemy. This repo provides a package to automatically select a random seed based on ancient Chinese Xua

Tong Zhu(朱桐) 33 Jan 03, 2023
A Collection of Cheatsheets, Books, Questions, and Portfolio For DS/ML Interview Prep

Here are the sections: Data Science Cheatsheets Data Science EBooks Data Science Question Bank Data Science Case Studies Data Science Portfolio Data J

James Le 2.5k Jan 02, 2023
Paper and Code for "Curriculum Learning by Optimizing Learning Dynamics" (AISTATS 2021)

Curriculum Learning by Optimizing Learning Dynamics (DoCL) AISTATS 2021 paper: Title: Curriculum Learning by Optimizing Learning Dynamics [pdf] [appen

Tianyi Zhou 15 Dec 06, 2022
A repository of links with advice related to grad school applications, research, phd etc

A repository of links with advice related to grad school applications, research, phd etc

Shaily Bhatt 946 Dec 30, 2022
A next-generation curated knowledge sharing platform for data scientists and other technical professions.

Knowledge Repo The Knowledge Repo project is focused on facilitating the sharing of knowledge between data scientists and other technical roles using

Airbnb 5.2k Dec 27, 2022
Course Materials for Math 340

UBC Math 340 Materials This repository aims to be the one repository for which you can find everything you about Math 340. Lecture Notes Lecture Notes

2 Nov 25, 2021