Deploy MkDocs to GitHub Pages (github.io)

Sat, 31 Jan 2026 00:00:00 +0000

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
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
mkdocs serve --dev-addr=0.0.0.0:8000

2) Create GitHub repository

# Run in your notes 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/<owner>/<repository>.git

# Example:
git remote set-url origin https://ghp_yourTokenHere@github.com/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 on Duke Hsu ｜ Learn • Build • Share

Deploy MkDocs to GitHub Pages (github.io)

1) Setup MkDocs environment

2) Create GitHub repository

3)Connect to remote GitHub repo

4)Deploy script (deploy.sh)

5)Math formula support (MathJax)