GitHub Pages - publishing through the online interface

May 27, 2016    Courses Tutorials

This is a tutorial about how to use your online interface to publish a project in GitHub Pages, GitHub’s website builder, directly from your code repository.

The process is neither obvious nor intuitive, but rather simple - and in this case we won’t resort to Git, command line or other more advanced resources programmers generally use to be faster and collaborate on the same repo, but that could be more difficult to learn at first.

GH-Pages is a good way for you to easly upload your website or project for free, without using any CMS.




  • First, open an account in no GitHub, if you don’t have one. It is free and fast.
    • Don’t forget to confirm this account - you will get an email asking you to do so.

Follow the red arrows!

  • After this step, access your main GitHub webpage, where you will be able to create repositories, files and sites

It will look like this

  • Now, you should create a new repository, by clicking in New Repository.

Not that hard!

  • Give a name to your repository. Inicially, right now it can be just /test
    • Give it a brief description to your project. Something like: this is a test, please don't mind this trial!.
    • A description is optional but it is useful and adds a good practice touch even to a test
  • Make sure to select the field Initialize this repository with a README.
    • This is particularly important, because if you don’t, GitHub will assume you are initializing and organizing your repo through a different process, and you will not be able to populate your project just yet. It is easier to just check it.

Life-saving arrows

  • The repo page must appear exactly as shown in the image below
    • Of course, note for any difference in title, content etc, but otherwhise should be the same

  • Now that you are in the repo page, this is where you will add your codes.
  • What you will do next is upload the codes, using either CTRL+C + CTRL+V or the upload files button
  • Add a description to your project if you haven’t done so, but ignore - for the time being - the field website.

Ignore the website field

  • If you want to copy and paste your code, click in create a new file button
  • If you want to upload files, like .html and .css, click upload files

  • In this example, I will proceed with the more arcaic approach: copying and pasting
    • Keep in mind that this is just a very simple, easy to implement approach, and its worth doing it to see how GitHub works
    • We will talk about the desktop client later
  • If you copy and paste, add a name to your initial HMTL file. In this case, as this will be your initial page (the only one for the time being in the repo), the name must be index.html
  • Paste the HTML in the field below Edit New File

Main file is <em>index.html</em>

  • Scroll down and give a description to your additions/changes if you want, and click the Commit button.
  • In this case, Commit would work like, roughly speaking, the Publishing button in a CMS
  • Don’t worry just yet with the option Create a new branch, it is used when you are making a separate branch in your repo, which its not our case right now

  • Now we have a published file in our repo. Note that no webpage is yet live - what we just did was uploading a file that will be published
  • We put our HTML out there, the basic structure. Now, we need to add the styles, the CSS
    • Do the same process you did before, if you haven’t uploaded both at the same time
  • IMPORTANT NOTE: remember to add, in the <head> tags of your HTML file, the link for the CSS, like this generic example: <link rel="stylesheet" href="home.css" type="text/css" charset="utf-8">
    • If you don’t remember how to do it, use the code above and just change the href=“#" value to link to your CSS.
    • If you CSS is in the same folder as the HTML, just add NAME OF CSS.css to the href. If it is in a folder, add FOLDER NAME/NAME OF CSS.css
  • If you are done with all the steps, we are almost there
  • Go to the main page of your repository, where are your HTML and CSS files
  • Just above the files, on the left side, there is a small box that says Branch: master
  • We will click on it and, in the text field, we will write gh-pages
  • Then Create Branch: gh-pages
    • This is how GitHub will understand that you will want a proper published page, not just the files in a repo
    • Again, the main page will be index.html.

Important

  • We are almost done
  • You page is practically published
  • In that field we ignored at first - Edit -> Website - we will add another thing, not so obvious but pretty simple
  • As GitHub uses its domain github.com for repositories, it redirects all GH-Pages sites to another domain, ending in github.io
  • In the field Website, add this: http://NAME OF YOUR REPOSITORY.github.io/**NAME OF THE PROJECT
  • Don’t forget the http:// prefix

Yeah!

  • Your project will be live in the URL you just added - click on it to see
    • Sometimes GitHub will take up to 30 seconds to recognize changes, so be patient
  • One last thing: now that you have to branches in the same repo, master and gh-pages, you need to prioritize gh-pages
    • If you do changes in master, you webpage won’t recognize it, because it is in a different branch
  • To make gh-pages you standard for this repo, go to `Settings_ > Branches > Select gh-pages in the box > Update
  • If you want, you can now erase the master branch in the branches tab back in your repo.
    • This won’t affect your page