Github User Pages in a Nutshell
To create a Github User Page: Make a repository on GitHub named yourGHusername.github.io, clone it, and push an index.html web page to it.
GitHub will host your site for free at the same address: yourGHusername.github.io, and the content in the index.html web page will be your site’s home page.
A. Create a Github User Page
- Sign in to Github.
- Open the Github Pages site, scroll down to Ready? Get Started, and make sure the User or organization button is selected.
- Open your shell, and cd to ~/Documents/repos/
- Complete the five steps as shown:
1. Create the new repo, select Initialize with a README.
For What git client are you using?, select A Terminal.
2. Clone the repo. Make sure you are in your repos directory, not your 281 directory.
3. Hello, World: this step creates a new file named index.html in your local repo on your computer.
4. In this step, you push your local repo to the remote.
5. Your user page will be available at https://yourUserName.github.io/.
It can take up to 1-3 minutes for changes to your site to publish after you push the changes to GitHub.
Debugging: By default, your user page will be published from the master branch. If for some reason this did not happen automatically as it should, open Configuring a Publishing Source for Github Pages, and scroll down to, Enable GitHub Pages to publish your site from the master branch.
B. Pick a Theme for your User Page
Open your remote repo in Chrome, and click Settings in the upper-right. Scroll to Github Pages section, and use the Theme Chooser to select a theme.
Selecting a theme will add a _config.yaml file to your remote repo, which applies the theme to your user page hosted at .github.io.
The theme is not applied to your local index.html page. To view the themed page you will have to push your changes to the remote repo, and then reload your User Page hosted at <yourGHusername>github.io.
Sync your Local and Remote Repos:
The Pull Command
When you pick a Jekyll theme for your User page on Github, that creates a new file (_config.yml) in your remote repo. Therefore, the remote repo has changes that are not in the local repo.
If you attempt to push from the local to the remote, git will respond with a “![rejected]” error.
Solution: run the Git Pull command to sync your local and remote repos.
Pull and Merge the Remote Changes
Run this shell command:
git pull origin master --no-edit
After pulling your changes from the remote repo, you should be able to use the push command as usual.
If the usual push command does not work, use the force push command once. After that, the usual push command will work:
git push -f origin master
C. Add Content
Edit your index.html file
- In Atom, use the File > Add Project folder to open your ~/Documents/repos/<username>.gihub.io folder.
- Edit the file index.html. Change the Hello, World content to start building a CIT Code Portfolio page.
- Add an image to the web page:
Create an images subdirectory in your repo directory, and store an image in it. Note: the image file size should be optimized for the web, and should not be a multi-MB behemoth.
Example: mh108.github.io
Create a README.md File.
In Atom, create a README.md file. Push your changes to Github.
Create a .gitignore File
Push your changes to Github.
index.html vs README.md
- index.html (or index.md) is your Github user page, so its content relates to you. It is your CIT Code Portfolio page, and is not related to just a single project. It is rendered and displayed at <yourUserName>.github.io.
- README.md is a description of the repo. It is rendered and displayed on the main page of your repo.
Example Github User Page
Example: oshaunessy.github.io