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.