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
- 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 ---
- 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
- Obsidian plugin Customizable sidebar could allow you to add button to automate the publishing procedure