GitHub Pages

Free web hosting for GitHub users

Prerequisites

Attention

Do ensure that you have compiled the web pages using MkDocs.

The relevant instructions can be found here.

  • Sign up for a GitHub account.

Type of Sites

For GitHub Pages, there are two types of web pages that can be created: Personal and Project Sites.

The following table summarizes the difference between Personal and Project Sites:

Personal Sites Project Sites
URL username.github.io username.github.io/project
Repository name username.github.io Any name
GitHub Pages Source master branch master branch /docs folder

Personal Sites

Attention

Your site will be at username.github.io.

To host a Personal Site on GitHub, start by creating a new repository on GitHub with the repository username.github.io, where username is your GitHub username.

Initialize the repository with a README.md file, and select Upload Files.

Drag and drop all the site files in /site/ and upload the site files.

Configure the GitHub Pages Source by navigating to the Settings of the repository. Ensure that the Source of the GitHub Pages is set to master branch.

If your GitHub Pages is configured correctly, you should see this message under the GitHub Pages section of Settings:

1
Your site is ready to be published at username.github.io.

Refresh the site in a few moments and the website should be up.

Project Sites

Attention

Your site will be at username.github.io/project.

To host a Project Site on GitHub, start by creating a new repository on GitHub.

Initialize the repository with a README.md file, and select Upload Files.

Create a new folder with the name docs in your file manager and place all the site files into this folder.

Upload the site files by dragging and dropping the entire docs folder.

Configure the GitHub Pages Source by navigating to the Settings of the repository. Ensure that the Source of the GitHub Pages is set to master branch /docs folder.

If your GitHub Pages is configured correctly, you should see this message under the GitHub Pages section of Settings:

1
Your site is ready to be published at username.github.io/project.

Refresh the site in a few moments and the website should be up.