GitHub 101 – Hosting a Static Website

Welcome!

Today, I am going to be showing you how to host your own static website using GitHub Pages. For this guide, I am going to assume that you can either learn HTML as you go or already have a tiny bit of knowledge on it.

---

Requirements

• A GitHub account
• A computer*

that’s it.

*arguably, you can use an iPad with a proper Git client and a great text editor from the App Store, but generally that’s not free.

---

Getting Started

Pick a Name for your Repository

A repository holds all of the code for your project – you can think of it as a place to hold your website or any other project you want to make. So first, let’s name it. Choose any name you want for your website, but keep in mind that it must be URL accessible.

Some example names and their URLs

name	site url, where treasure-hacks would be replaced with your username
treasurehacks-site	https://treasure-hacks.github.io/treasurehacks-site
site	https://treasure-hacks.github.io/site
super-octo-doodle	https://treasure-hacks.github.io/super-octo-doodle
treasure-hacks.github.io	https://treasure-hacks.github.io/

If you put username.github.io, where username is your GitHub username, your end URL will be the root subdomain (username.github.io). Otherwise, it will be username.github.io/repo-name/

Initialize the Repository on GitHub

• Log in to GitHub
• Create a new repository
• You should be here:
• Enter the repository name and an optional description (if you want)
• Choose Public (unless you have GitHub pro, you won’t be able to host it on GH Pages if you choose private)
• You can choose to add a README file if you want, as well as the other two. The README file is written in markdown, which will be formatted almost exactly like any post you make on this forum. This will show up below the code when anyone visits the repository.
• You should have something like this:
• Click “Create repository”

Enabling GitHub Pages

1. Go to your repo settings
2. Click the pages tab on the left
3. Choose branch main and leave the folder as root
4. Great! Whenever you push files here, GitHub will automatically generate your site for you.

Setting up the repo locally

You can do this one of two ways:

1. Using a Git client such as GitHub Desktop
2. Use the command line (Terminal, Command Prompt, etc.)

For ease of use, we will be using the first method in this tutorial. If you are comfortable with the command line, you can look at the git documentation to find the equivalent actions.

Before starting, what is Git?

• Git is a form of version control. What that means is that it tracks any changes you make locally or remotely, and across different “branches”
• The base branch is typically main, and other branches you make are based on the latest version of main at time of creating.
• Branches allow you to have a separate copy of the code so that you can make changes without breaking your “production” build (production is a public copy that you show to everyone)
• For now, we’ll just work with main to avoid any confusion you might have with the concept of branches.
• Since Git tracks your changes, it will show when you’ve made local changes to a file. Once you’ve tested your files, you’ll push the change to the remote Git server (in our case, that means uploading the changes to GitHub)
• If someone else (or you on a different device) makes changes in a branch of code, you can pull those changes, meaning download them to view/edit locally

---

1. Download the Git Client you’re going to use (I’ve linked GH Desktop above). This app will track any local changes you make and upload your files to GitHub to host your website. Note: GitHub Pages only hosts static webpages. If you want to make a server app, you can still host the code on GitHub, but the server code will be hosted/run on another platform like Heroku.
2. Open the app, log in, and change any preferences you wish to change.
3. Go to Add > Clone Repository. Enter the URL of your repository that you made on github.com. The repository URL is of the format https://github.com/username/repo-name, where username is your GH username and repo-name is the name of the repository.
4. You should see this:
5. Once you choose your local path (that’s where GH will store your repo on your computer as you work on it), click clone.

Once you get here, congratulations! Your repository is now on your computer, ready for you to make changes.

---

Making Your First Changes

Now, let’s make the first change to your project. Let’s open up an IDE (integrated development environment) such as VS Code and get started.

You don’t have to use VSCode – in fact you can use any text editor (TextEdit, Notepad, Notepad++, TextMate, etc.) – but an IDE like VS Code or Webstorm will help you track changes, give you syntax highlighting, and so much more. For this tutorial, I’ll use VSCode.

You should see something like this when you first open VSCode:

1. Click Open... (under “Start”) and find the local path of your repo. Choose the folder that matches the name of your repo, e.g. super-octo-doodle or site.
2. Trust the author (since that would be you)
3. Move your mouse to the left, and you should see some icons appear, most notably the first two (new file and new folder).
4. Click the new file icon, and let’s title our first page index.html
5. You should be here at this point:
6. Type ! then hit enter. Change the title of the doc, and add some text or HTML of your choice into the editor. Save the file, and you can now open it in your browser. You should see this:
7. Once you’re content with your first webpage, open your Git client (GH Desktop) to push the changes to remote.
8. To record your changes on version control, you create a commit. You will do this every time you update your website. Creating a commit is simple: click commit to main.
9. This records the changes locally. To then upload these changes to GitHub, press push to origin. You should see some progress bars, then it should be done.
10. Once you’ve done that, you can check your website URL at https://username.github.io/repo-name (if the name of the repository is username.github.io, omit the repo-name). You should see that same page you just created.

Fantastic – you are now able to make changes locally, do a basic load test in the browser, and push to GitHub to create your website!

But, there’s one problem right now: local files. They have some of the behavior of a URL, but they’re not quite the same. Requests often won’t work, pointing to a folder doesn’t load the index.html file, and other browser features are disabled. To fix this, keep reading on how to start a local http server to test out the changes.

---

Development Server

Here’s some helpful information on why you should use a local server instead of just using file and on how to get it set up. Follow this until you’ve installed Python. If you’re on a Mac, python is preinstalled with the machine. https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server

1. Go to VS Code, and press ctrl + ` (control and the key above the tab key) to open up your command line. (on a Mac it is also control, not cmd)
2. Check which version of python you’ve installed by running this command: python -V
3. Since you are in VS Code, your command line is already in the directory of your project. Enter the appropriate command to start a server at that location:

# If Python version returned above is 3.X
python3 -m http.server
# On windows try "python" instead of "python3", or "py -3"
# If Python version returned above is 2.X
python -m SimpleHTTPServer

1. You should see this:
2. Now, you can go to http://localhost:8000 in your browser, or if that doesn’t work, you can try http://0.0.0.0:8000
   ^{If your repo name is username.github.io, you're done.}
   However, if your repo has a name that isn't username.github.io, the index.html is served at different locations locally and remotely. Locally, it's served at the root path (localhost:8000/, where the path is highlighted in orange). Remotely, it is served at username.github.io/repo-name/
   This makes a difference when writing links and referring to URLs relative to root. If you want to load an image at `root-of-repo/image.png`, it would be `/image.png` but remotely `/repo-name/image.png`

3. To fix this, we can stop our server with control + c (not cmd + c), and change directory to parent by typing this: cd .. Your command window should show username@device-name GitHub % or something like that, where GitHub is the parent folder of your repository.
   

4. Start your server again with the command in step 3, and this time you’ll go to localhost:8000/repo-name, and you should see your website again, but this time at the correct path: Nice how the only difference between your local URL (localhost:8000/repo-name/) and your remote URL (username.github.io/repo-name/) is the host (blue), whereas the path name (orange) is the same. This will make the development environment consistent with the remote environment.

Awesome! You’ve set up your own local development server to test your webpages on.

---

Rinse and Repeat

Using the knowledge you’ve just gained, here’s a process on how you can make changes to your website:

1. If you just opened your computer, start VS Code and start your local server (see commands above). You may need to go up a directory with cd .. as mentioned previously.
2. If you made changes on another device, open GitHub Desktop and pull (download) those changes.
3. Make changes by editing files, adding new files, adding new folders, deleting files, etc. in your editor, e.g. VS Code.
4. Save the changes, and go to localhost:8000/repo-name/
5. Test your page(s) to make sure it works.
6. Go to GitHub Desktop, commit the code, and push to origin.

That’s the basics of testing and hosting a website using GitHub pages. It may seem like a lot of work, but you’re learning concepts that you can apply to future coding ventures that will often have you set up GitHub repositories and run local servers to test your applications. I hope you found this helpful, and I can’t see what you make!

Please feel free to ask any questions, share your GitHub websites, or talk about the process and/or get advice/tips related to coding your site.