Deploy MkDocs to GitHub Pages (github.io)

1) Setup MkDocs environment

## Create MkDocs virtual environment
python3 -m venv mkdoc_venv

## Activate venv
source mkdoc_venv/bin/activate

## Deactivate venv
deactivate

## Install MkDocs + Material theme
pip3 install mkdocs mkdocs-material

## Install Mermaid plugin using pip
pip install mkdocs-mermaid2-plugin

## Create a new MkDocs project
mkdocs new duke-note

## Run MkDocs local server
mkdocs serve

## Run server for external access (0.0.0.0)
mkdocs serve --dev-addr=0.0.0.0:8000

2) Create GitHub repository

##running on your note directory
git init
git add .
git commit -m "Initial commit of my study notes"

3)Connect to remote GitHub repo

## Format:
## git remote set-url origin https://
<TOKEN>@github.com/<USERNAME>/<REPO>.git
## Example:
## git remote set-url origin https://[email protected]/dukehug/mkdocs_dknotes.git

git branch -M main
git push -u origin main

## Deploy to GitHub Pages
mkdocs gh-deploy

4)Deploy script (deploy.sh)

## !/bin/bash

## Stop if any error happens
set -e

## Build site
mkdocs build
sleep 10

## Push updates
git add .
git commit -m "update notes: $(date)"
git push origin main
sleep 10

## Deploy to GitHub Pages
mkdocs gh-deploy

5)Math formula support (MathJax)

References:

MkDocs Material Math https://squidfunk.github.io/mkdocs-material/reference/math/#mathjax-docsjavascriptsmathjaxjs

HackMD https://hackmd.io/cNmSPyWlTqGaQdX8eKCZew

GitHub Repo: https://github.com/dukehug/mkdocs_dknotes