Skip to content

Git pages


Some notes on how to setup a Github Pages website that is hosted on and served from a public Github repository.

Upsides are that it's pretty effortless to maintain and add new content with Github CI pipeline ( auto build/deploy site ) and it is free ( if using default '' domain ).

# My workflow with this setup if usually something like this:
1. Move to the local repository
2. code .
3. Open a file and 'Open preview to the side'
4. Edit some notes
5. Commit and push

# Occasionally, instead of 'open preview to the side' I use 'mkdocs serve'
# to run a local web page if I need to see how the formatting, table of contents
# and other layout related things look like

Tools needed

  • Github account
  • Git
  • Git LFS ( Needed for images, videos and other binary data )
  • Python

Setup git and git lfs

# Setup Git

# Create a common folder where your Git repositories go, for example

# Install Git LFS

# You should have 'Git Bash' installed in Windows, open it and
cd /c/work/git

# Setup Git LFS
git lfs install

# Add files to LFS separately by filetype
git lfs track "*.png" 
git lfs track "*.jpg" 

# OR add all binary data to same folder and add only that
git lfs track "binary_data_folder/**"

Setup env

python -m venv venv
source venv/Scripts/activate

# Install dependencies
pip install mkdocs-material

# ( Optional ) Install other dependencies
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-glightbox

# Create new project
mkdocs new .

# Run local page:
mkdocs serve

# Note: If you are hosting images externally, access the website using localhost,
# instead of, otherwise the images won't show up for some reason.

Setup build/deploy pipeline

# Create Git workflow setup
mkdir projects/.github/workflows
touch ci.yml

# Add to ci.yml:
name: ci 
      - master 
      - main
  contents: write
    runs-on: ubuntu-latest
      - uses: actions/checkout@v3
          lfs: true
      - uses: actions/setup-python@v4
          python-version: 3.x
      - uses: actions/cache@v2
          key: ${{ github.ref }}
          path: .cache
      - run: git lfs checkout
      - run: pip install mkdocs-git-revision-date-localized-plugin
      - run: pip install mkdocs-glightbox
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

⚡ Note: lfs: true this did not work for me, had to add the - run: git lfs checkout step to make Git Pages load images from Git LFS

Add content

# Project structure is as follows:
- .github/
  - workflows/
    - ci.yml
- docs/
  - Projects/ # Name can be whatever
    - Project/ # Name can be whatever
      - # Name can be whatever, this will Show up as 'Git pages' link
  - stylesheets/ # Optional, for custom themes
    - styles.css
  - venv/ # Created by python, add to .gitignore
  - # This is the home page
- .gitignore
- .gitattributes
- mkdocs.yml

# Create the above file structure and keep adding Project/ folders and .md files
# under them. Alternatively, you can create sub folders under the Projects/ to
# add gategories

For example, this page is just a markdown file here:

Setup custom domain name ( e.g. )

I have added some notes on my notes/ site on how to setup custom domain and email