Documentation publishing with Obsidian and GitHub Pages using mkdocs

Pasted image 20220305205209

Workflow description

I’m using Obsidian as MarkDown editor. It supports lot of useful features (like wikilinks) as well as hundreds of useful plugins like task management, Dayly notes / planner, templates or dynamic content generation (for overviews).

GitHub Pages are than generated through MKDocs I’m using also obs2mk script which picks the notes to be shared from Obsidian and put them into appropriate directory structures mkdocs could use.

I also customized Obsidian’s side panel and added here a clickable button which will trigger whole workflow

Requirements

  • Python 3.9 - install it from your OS repository
  • pip - package manager for Python, you could install it from your OS repository as well.
  • git - install through your OS repository
  • mkdocs - static web site generator
  • obs2mk - interface between Obsidian Vault and mkdocs
  • mkdocs template - set of CSS, assets and configurations for fencier appearance of your pages.

Step 1: Get the template, install mkdocs and obs2mk

  • Get the template and create your main branch
      

git clone -b template --single-branch https://github.com/Mara-Li/mkdocs_obsidian_template blog
cd blog
git checkout -b main
  • Install mkdocs, obs2mk and all the requirements
pip install mkdocs
pip install obs2mk
pip install -r requirements.txt

Step 2: Configure your new site

Edit the mkdocs.yml according your needs - you will need to update yust few parameters

site_name: Martin Sukany's workplace
site_description: ... pieces from my second brain ...
site_url: https://pages.github.kyndryl.net/Martin-Sukany/blog/

Step 3: Configure obs2mk

Obs2mk should be pointed to your obsidian vault as well as the repository containing template and your site at this moment.

      

martin@Martins-MacBook-Pro blog % obs2mk --c
**Creating environnement in** **/usr/local/lib/python3.9/site-packages/mkdocs_obsidian/****.mkdocs_obsidian**
Please provide your **obsidian vault** path: /Users/martin/tresor
Please provide the **blog** repository path: /Users/martin/work/blog
Choose your share key name **_(_**_default:_ **_share)_**: 
Choose your default folder note **_(_**_default:_ **_notes)_**: hidden
If you want to use folder note, please choose the key for citation **_(_**_default:_ **_(i))_**: 
 Environment created !

Step 4: Prepare your notes to be published

In obsidian add the like the following ones at the begining of your document to be published:

---
tags: 
  - obsidian
  - mkdocs
  - obs2mk
share: true
category: Documentation
---

where

  • share (mandatory) defines if the note should be shared or not
  • tags (optional) specifies the keywords assigned to the note - you can i. e. search for these words on your site
  • category (optional) defines the section of the site where the document will be shown. Unless defined, default is used. I’m personally uusing hidden as the default one = notes are note directly accessible from the main page (useful when you want to refer to some note through linking to another one).

Step 5: Publish your note

obs2mk
mkdocs gh-deploy --force

Tips

  • Obsidian plugin Customizable sidebar could allow you to add button to automate the publishing procedure
Tags
Workflow