Setting up github for a static developer journal

Set up a Github Pages repository on Github

Create a new repository

To create a new repository on Github, you can click on the '+' button next to your profile image on the top right hand side of the screen.

Then you can click the 'New repository' button which will bring you to the page where you configure your new repository with a name and privacy details etc.

Name your repository like this: "username.github.io"

Name your repository like this: 'username.github.io' Your username must exactly match the username associated with your Github account for this to work, case sensitive.

Select the 'public' option to mark your repository as public

Your repo can be private, but the Github pages website itself will be publicly accessible to anyone who knows the link, which is easy to find out because it's just your username followed by github.io.

Click on the green 'Create repository' button at the bottom of the page to finish creating your Github pages repository

inish creating your project. After creating your repository, you will be brought to your repositories home page. This page includes instructions for setting up your repository on your local machine.

The instructions in the following instruction shows you how to set up a static webpage with version control. These instructions provide reasons for why you may or may not want to do something, as well as a few tips that should help make your life easier should you decide they could work for you.

Create a homepage and see it live on Github Pages (terminal)

I use the terminal, but you can also use the Github Desktop client if you prefer. Here are instructions for both cases.

Go to the folder where you want to store your repository on your computer

Create a homepage and see it live on Github Pages (terminal):

I use the terminal, but you can also use the Github Desktop client if you prefer. here are instructions for both cases.

I store my project folders in the home directory. When you open up a fresh terminal, you are automatically in the home directory so you don't need to navigate anywhere else like the Desktop to find your folder.

If your are in any other folder, you can navigate directly to the home directory by running the cd command.

Clone your Github Pages repository to your chosen folder

Go inside your cloned folder

Instead of typing out the full name of the folder you want to go inside, you can enter the first few characters and hit the 'Tab' key to autocomplete it.

Add and index.html page to your Github Pages repository.

The index file is the home page of your website. We call it an 'index' file because it contains an index that people can use to look up places in your website that they want to visit.

Open your index.html file and add a title to it

Your title can be anything. I wrote a standard 'Hello World!' message. You can add the boilerplate setup later. We just want to see that the Github pages site can display the webpage you have just created.

Stage your index.html file to be committed:

You could also have used `git add .` to add all of your files (in this case there is only one) to be committed. Though I would advise against doing this for two reasons:

1. If you add files this way on bigger projects you might accidentally add files that you don't want to commit.
2. Or you might end up committing a lot of files with a single commit message, whereas committing them in smaller chunks will allow you to write more meaningful commit messages that express what you were doing better.

Commit your file with a meaningful commit message:

Most tutorials instruct you to write your first commit message as 'first commit'. The same tutorials tell you that the best commit messages explain why you have done something instead of how you did it, which is contradictory considering the first commit message does not explain why you are making the first commit.

The first commit message is an ideal place to start explaining why you are starting your project. Again this is a personal preference, but one that makes my commit messages read like an interesting story that evolves over time with a meaningful narrative.

You can stage files and commit them in one step by combining the commands with the '&&' operator like this:

Push your index.html homepage to your Github Pages website

git push origin master NOT git push -u origin master

One of the reasons I document everything I learn as I learn it is to make sure that other self-taught devs have access to the same information that I am priviledged to have access to. Hence the detailed explanations about 'why' we do things and what could go wrong with them.

At this point, most tutorials tell you to use `git push -u origin master` to push your changes to the upstream repository, but this command can cause unintended consequences that have been outlined below.

Before we look at the consequences, I'll explain what the `git push -u origin master` command does. This explanation requires an understanding of the difference between a downstream and an upstream repository.

• A downstream repository is a repository that we have copied, cloned or checked out. By cloning a repository, the information contained within the original repository has flowed downstream to us.
• Whenever we make a change to our local repository that we want to share with a main repository (usually hosted on a version control server), we push our changes upstream.

In the 'git push -u origin' command, we are saying:

Push all of the changes we have made in our downstream repository (local copy) to our default upstream repository (that we are about to set). We want our default upstream repository to be the origin of our master branch, or in other words the location where we cloned our repository from.

The '-u' flag sets the default upstream repository to whatever location (branch) is specified.

After we have set our default repository, we no longer need to specify the repository that we want to push/pull our changes to/from. We can just use `git push/pull` instead of `git push/pull origin [branch]`.

While setting the upstream repository seems convenient, it can cause problems depending on what version of Git you are using (especially versions < 2.0), and depending on how Git is configured in the git config file/s.

You can check how Git is configured you can run `git config -l`. To find out what version of Git you are using, you can run `git --version`.

In Git versions before git 2.0, the default settings for 'git push' is to push all branches locally that have the same name on the upstream repository.

The good news is that in Git versions 2.0 and after, the default settings for 'git push' is to only push the branch you are currently working on (if it has the same name on the upstream), which is much better.

That being said, even if the version is current, the Git config settings may have set the default push settings to match an earlier version's way of doing things (possibly because `git push/pull` appears to be more convenient and most tutorials don't teach the problems).

Chances are, you are not going to remember to check the version of Git being used or the config file settings for all of the repositories you are working on.

The safe option then is to push your changes using the 'git push origin [branch]' command.

Using this command means that you are always being explicit (and intentional) about the changes you are pushing to your upstream repository.

You have now pushed your markdown homepage to your Github Pages repository.

Access your live Github pages URL

Open your browser and type in `https//username.github.io`

If you try to access your Github Pages website straight away, you are likely to get a 404 error page. This is because it can take up to 10 minutes for your site to be 'built' and made live by Github.