Today, I am going to be showing you how to host your own Hopscotch 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.
- A GitHub account
- A computer*
*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.
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 awesome-e would be replaced with your username|
- 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”
- Go to your repo settings
- Click the pages tab on the left
- Choose branch main and leave the folder as root
- Great! Whenever you push files here, GitHub will automatically generate your site for you.
You can do this one of two ways:
- Using a Git client such as GitHub Desktop
- 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
mainto 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
- 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.
- Open the app, log in, and change any preferences you wish to change.
- Go to Add > . Enter the URL of your repository that you made on github.com. The repository URL is of the format
https://github.com//, where is your GH username and
repo-name repo-nameis the name of the repository.
- You should see this:
- 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.
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:
Open...(under “Start”) and find the local path of your repo. Choose the folder that matches the name of your repo, e.g.
- Trust the author (since that would be you)
- Move your mouse to the left, and you should see some icons appear, most notably the first two (new file and new folder).
- Click the new file icon, and let’s title our first page
- You should be here at this point:
!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:
- Once you’re content with your first webpage, open your Git client (GH Desktop) to push the changes to remote.
- 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 .
- 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.
- Once you’ve done that, you can check your website URL at
https://.github.io/(if the name of the repository is .github.io, omit the
repo-name 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.
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.
- 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)
- Check which version of python you’ve installed by running this command:
- 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
You should see this:
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 , you’re done.
However, if your repo has a name that isn’t .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
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
To fix this, we can stop our server with control + c (not cmd + c), and change directory to parent by typing this:
Your command window should show
username@device-name %or something like that, where is the parent folder of your repository.
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 (
/repo-name/) and your remote URL ( /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 (E)! You’ve set up your own local development server to test your webpages on.
Using the knowledge you’ve just gained, here’s a process on how you can make changes to your website:
- 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.
- If you made changes on another device, open GitHub Desktop and pull (download) those changes.
- Make changes by editing files, adding new files, adding new folders, deleting files, etc. in your editor, e.g. VS Code.
- Save the changes, and go to
- Test your page(s) to make sure it works.
- 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.