Create a Website with Github Pages


If you have a project, blog, or documentation that you need to have hosted in a site, Github Pages can be a great way to host your site for free straight from the repository.

Since this website itself was made with Material MkDocs, this tutorial will explain how to build and deploy a static website to Github Pages using that.

Install Python

MkDocs is built using Python, so we will need to install Python first in order to build and run anything. Since Macs by default have Python 2 installed, we will need to install Python 3 to use MkDocs. The easiest way to install Python 3 is with Homebrew.

brew install python

Once installed, you should be able to verify this by running the following command to see the version number.

$ python3 -V
Python 3.7.7

If you wish to use the python command in the terminal and have it reference the python3 version. Following this article, we can create an alias in your bash profile that will reference the python3 version. First get the path of where python3 was installed.

$ which python3

Now add an alias to your bash profile file that will now make any python command in the terminal point to the python3 version instead of Mac default of python2.

alias python=/usr/local/bin/python3

After sourcing your bash profile with the new alias, you should now be able to just use python in the terminal instead python3.

Download and Install Material MkDocs

Using Github

The easiest way to get running is to fork the repository from Github and then clone that repository to your machine.

Fork Github Repository

Now in order to access your website in the public space in the end, we must rename the repository to <username> in order to work with the default domain given for free from Github Pages. Go to the settings of your repository, and rename the repo with your username replaced.

Rename Forked Repository

Now we can clone the repository to our local machine with git.

!!! note I am using the the SSH urls when cloning, you could just as easily use the https urls. If you have not set that up in git and wish to learn how, checkout how to use SSH.

`git clone`
git clone

Enterprise Github

In case you are working with an enterprise instance of Github that has a different domain and is not publicly accessible without some form of authentication. Then just go ahead and clone the Material MkDocs repository directly and add your enterprise’s remote url.

git clone
git remote add enterprise
git push enterprise master

Running Material MkDocs Locally

First install all of the Material MkDocs dependencies with Python’s package manager, pip.

pip install mkdocs-material

Then to run the server, you can run the following command on the mkdocs python module.

python -m mkdocs serve

Open up your browser and navigate to and you should now see the landing page for your Material MkDocs site.

Material MkDocs

!!! note If you run into an error when running the command above with the following

MkDocs encountered as error parsing the configuration file: while constructing a Python object
cannot find module 'materialx.emoji' (No module named 'materialx')

Then comment out the following lines in the `mkdocs.yml` file since you probably don't need the emoji dependency right away. 

# - pymdownx.emoji:
#     emoji_index: !!python/name:materialx.emoji.twemoji
#     emoji_generator: !!python/name:materialx.emoji.to_svg

Deploying Your Site To Github Pages

Deploying to Github

To access your site publicly from any broswer, we can now deploy it with the following command.

python -m mkdocs gh-deploy

Be sure that the repository settings is configured for Github Pages to be built off of the gh-pages branch as this is the default branch MkDocs will deploy to.

If you are creating a personal Github Pages website for your username and do not see the option to switch the branch. This is because it must be built off of master which is an easy fix to deploy to.

From the master branch, checkout a new branch and call it develop then push it to Github. Now you can configure MkDocs to deploy to the master branch instead of the default gh-pages branch.

git checkout -b develop 
git push origin develop
python3 -m mkdocs gh-deploy -b master

Deploying to Github Enterprise

To deploy to your enterprise instance of Github, you must make use of the remote flag to tell MkDocs that it should deploy to the gh-pages branch on your remote repository.

python -m mkdocs gh-deploy -r myfork

The easiest way to figure out your url for you enterprise Github Pages site is to go to the repository’s settings, and go down to the Github Pages section to see where it was published.

Enterprise Github Pages Name

Configure Custom Domain for Github Pages

Managing Custom Domain - Github Docs article for configuring Github Pages with custom domain on Google Domains.

Deploying MkDocs CNAME - adding a CNAME file in the docs folder that contains the domain name that was used in the custom domain field in the repository settings will allow the mkdocs gh-deploy command from wiping out the CNAME file in the master branch.

If you happen to get the following warning when updating the custom domain in your Github repository settings. I found out there was another repository on my account that had the custom domain already setup and deleting that custom domain on the other repository fixed my issue.