A Live Developer Journal

Setting up github for a static developer journal

table of contents

Set up an empty Github pages repository on Githubi

  1. Create a new Github pages repository
  2. Name your repository
  3. Mark your repository as public

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

  1. Clone your repo pages repository
  2. Add an index page to your repository
  3. Stage your index page to be committed
  4. Commit your index page
  5. Push your index file to your upstream repository (**READ THIS**)
  6. Access your Github pages website

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

git clone https://github.com/username/username.github.io

Go inside your cloned folder

cd username.github.io

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.

touch index.html

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:

git add index.html

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:

git commit -m "home page available to start sharing dev journal entries"

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:

git add file.html && git commit -m "commit message"

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.

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.

Problem Scenario

You are on the master branch and you make a few changes only to realise that you meant to be on a different branch. So you switch to a different branch, make a few changes and push your changes. You forgot to reset your master branch before you pushed. As the master branch is known to the upstream repository, you have accidentally pushed changes. This is pretty difficult to undo.

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.