Publish vault with Obsidian Github Publisher and mkdocs

In a beautiful day, I have interest to publish a trading journal using mkdocs. In my setup, I use the GitHub Publisher plugin to send the notes written in Obsidian, into a GitHub repository, then deploy on Netlify and Cloudflare Pages.

Steps to install and configure

with Netlify

Create a new repository from this template 1. This new repo will be called trade-bt-mkdocs
Connect my Netlify account to the repo trade-bt-mkdocs and deploy via Netlify
- Retrieve the URL of deployed site in Domain settings within Netlify
- Read the tutorial in details to learn how to deploy
Since I deploy via Netlify, I have to modify the requirements.txt as discussed at here
- Change: obsidiantools==0.10.0 -> obsidiantools==0.8.1. Reason: Netlify only support python 3.8
Configure in "GitHub Publisher" plugin settings
- Create a personal access token (classic) then paste it into the "GitHub Token" field in "GitHub Configuration" tab. Also change "Repo Name", "Github Username"
- I did not choose the new fine-grained personal access token as instructed 2, because it requires an expiry date within 1 year, and I don't want to set an expiry date for this token
- In "Plugin Settings" tab,
  - change "Share Key" to dg-publish. Reason: I want to use the same publishing keyword with Obsidian Digital Garden
  - change "Excluded Folder" to 99_template. Reason: I don't need to publish any notes within this folder
- In "Upload Configuration" tab,
  - set "Folder behavior" to Obsidian Path. I want to replicate the folder structure of Obsidian vault to the published site 3
  - set "Default folder" to docs
Close and reopen Obsidian to assure that the changes are executed. Because I also encounter the same error as this user's issue
Configure the file mkdocs.yml in the repo trade-bt-mkdocs
- change the site_url into the valid Netlify link from previous step
- add the Navigation footer to include links to the previous and next page of the current page
- change the colors
- change the fonts
- change the logo and icons
- (optional) set up the navigation tree. I didn't do this step. Because i don't want to change manually the items in the navigation tree whenever I change the file structure
- add a git repository
Enable the Comments section for specific page only
- Update 20230114, according this reply of plugin developer, she has recently updated the template. Please follow her updated tutorial to learn how to enable the Comments section for specific page only
- Read here to understand why the key template: custom.html works
- In this section, the author explain how to extend the mkdocs-material using the custom_dir setting, what's the meaning of folder overrides, partials
- (obsolete, update 20230114) in GitHub repo, path trade-bt-mkdocs/overrides/, duplicate the main.html as page_comments.html. After that, in the note (page) where I want to enable the comments, I will add the key template: page_comments.html in its frontmatter. 4
(Optional) Disable the workflow Building Mkdocs Page in GitHub Actions 5, since I deploy solely via Netlify. This only helps the repo status clean. It does not affect on the success of build process.
Create a custom front page
- Follow this issue and replicate a home.html with examples from up42-py, le-ref-architecture-doc, mkdocs-material

with Cloudflare Pages

Create a new repository from this template. This new repo will be called trade-bt-mkdocs
Connect my Cloudflare account to the repo trade-bt-mkdocs and deploy via Cloudflare Pages
- Retrieve the URL of deployed site in Domain settings within Cloudflare
Since Cloudflare Pages support only up to python 3.7 1, i need to modify the file trade-bt-mkdocs/runtime.txt from 3.8 to 3.7. And also modify the requirements.txt as in configuration step with Netlify
From step 4 through 9, they are similar to the Netlify part.

How to write notes and then publish?

Write note in Obsidian
In the note's frontmatter, add the key dg-publish: true. This action mark that this specific will be sent to the trade-bt-mkdocs repo and then deploy via Netlify
CTRL + P to open Command Palette in Obsidian, search for
- command Github Publisher: Share active file to send only this active note
- or command Github Publisher: Upload all shared note to send all the notes with the key dg-publish: true

Notes

Working folder of a mkdocs repository

Each Markdown file inside the folder docs will be rendered as a page of the site. The index page is located at docs\index.md. Sub-folders are used as the path to a group of related posts.

If a post is named other than index.md, the filename will be used as the directory path of the generated page. Here is how MkDocs generates URLs for Markdown posts: