Tutorials > Github

Setting up Github Pages

A guide to setting up Github as a webserver using only a web browser

Quick note: This guide really isn't for everyone. In my class, students have a variety of OS setups, not all of them that meet the minimum requirements for the Github desktop client. If that's not a problem with you, then that's what you should be using. This approach works via just the web browser, but without all the conveniences of the command-line or the desktop client.

This is a simple step-by-step walkthrough on how to create a new Github repo – referred to as the Github Pages feature – that can specifically be used to host and publish custom web pages, including testing out interactive web features (such as maps) or even creating your portfolio.

By the end of this walkthrough, you'll have a repo that, when you submit files to it, they'll immediately be served on the Web. You technically are already doing this with pretty much any Github repo you make, but Github Pages lets you basically publish any kind of webpage (not just things hosted in Github's template).

Fair warning: Everything you commit to this repo will be accessible to the entire Web. So don't post any dummy text you wouldn't want the world to see.

Create a new repo

In the screenshots and video clips, I'll be using an account named danksnguyen. Anytime you see that name, just substitute your own Github username.

  1. Click the + New repository button

  2. You must give this new repo a very specific name:

     username.github.io

    Or in my example:

     danksnguyen.github.io
  3. Go ahead and Initialize this repository with a README and leave it set as Public.
  4. Click the Create repository button.
Video

Watch me create a Github Pages repo:

Edit your README.md

This step is entirely optional and just meant as a proof-of-concept, i.e. the further confirmation that a "Markdown file" is just a text file and not really HTML for the web browser…unless you have a site like Github.com doing some behind-the-scenes magic. We'll see what happens when that magic doesn't exist.

  1. Click on the README.md file
  2. Click on the little pencil icon (which stands for Edit file)
  3. Write some stuff in Markdown. Here's a cheat sheet.
  4. Hit the Commit Changes button.
Video

This README.md file is actually already published to the web. In fact, you can visit it directly at this URL:

http://username.github.io/README.md

And it will look like this:

img

Check out that new subdomain

Hey, that's just raw text, what gives? The difference is that under the domain of: 

http://username.github.io/README.md

– the raw files (remember that Markdown is just text) are being served up. This is in contrast to what lives at:

https://github.com/username/username.github.io/README.md

Basically, by naming your repo, username.github.io, Github has carved out a place on the web for you at http://username.github.io. That's all.

Publish some real HTML

Since your README.md is just plaintext, it's not served up as a real web page. For that, you'll have to write up your own HTML (yes, that's a pain).

Follow these steps:

  1. Go back to your repo page on github.com

    e.g. https://github.com/username/username.github.io

  2. Create a new file by clicking on the +
  3. Name this file test.html

  4. Go to town on writing some HTML. Or you can just copy this:

      <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8">
      <title>Document</title>
    </head>       
    <body>
       <h1> This is my test page <h1>          
       <img src="http://placekitten.com/g/300/300"
       <p>Kitty says: <strong>Meow!</strong></p>
    </body>
  </html>
  5. Commit the changes

  6. Visit the page at username.github.io/test.html

    img

  7. Congratulations, you are now a web developer.
Video

Watch me create a web page from scratch:

Go crazy

To see how much publishing power you now have, let's rip off all the code from another webpage.

Note: If you are using the Safari Browser, you will need to enable the Develop menu in order to complete this step:

Go to Safari > Preferences in the menu bar, then select the Advanced tab. You should see a checkbox named Show Develop menu in menu bar. Check that box and you should be good to go.

img

Ripping Wikipedia
  1. Go to any Wikipedia page of your choice

  2. View its source.

    • In Google Chrome, this is hidden under the menu item: View > Developer > View Source
    • In Safari, this is usually under Develop > Show Page Source
    • In Firefox, look under Tools > Web Developer > Page Source
  3. Select all the code and Copy it to your clipboard.

  4. In your github.io repo page, i.e.

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

    Make a new file, name it something like hooray.html, and then paste everything you copied into the file body and commit the changes.

  5. Now visit: username.github.io/hooray.html

    img

  6. Congratulations, you are now a content aggregator.
Video

Watch me recreate a Wikipedia page:

Conclusion

That's as far as we'll go right now. The important thing to know is that you can now publish basically any kind of webpage you want and have it hosted at username.github.io. This will be useful as you create custom web features that need to live somewhere besides your laptop's hard drive.

Additional help: