How to Host a Hopscotch Website on GitHub

Welcome!

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.


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

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.

  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 (E)! 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!

I’ve seen this asked a lot lately, so I thought I’d make a post on this
@Good-Es @omtl

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.

22 Likes

Here’s some Q and A – I’ll add to this as questions are asked

  • "When and why did you get into this?"
    • I was into website design for quite some time, and I have used website builders in the past to showcase my creations. I had videos, projects, a couple “articles”, and more on my Hopscotch Website (at the time on Google Sites).
    • Once the new guidelines came in early 2019, however, I had to remove all links and close all threads with links to the site, for Google Sites had been banned to better moderate user content on the forum. As you might imagine, I was a bit upset by this, but later took the time to learn how to share websites that were open-sourced (since that remained allowed).
    • I’ve always poked around the Developer Tools (Inspect Element) in browsers (some of you might have as well), so I knew a little bit about how HTML works. So I started with CodePen embeds/pages. Pretty soon, however, I felt the need for a file system like many websites have to better host my creations.
    • That’s when I began to use GitHub to store code that I wrote outside of Hopscotch. I had an idea of something I wanted to make in HTML (the language that creates web pages), and in the very beginning, I created three different pages: a Hopscotch Help Guide page which rendered blocks and some information about them, a help guide for my Hopscotch JSON Siri Shortcut which gaining traction, and a page for videos I wanted to share (this was before YouTube links were allowed again).
    • Ever since then, I’ve just been expanding on my creating, and that is what led to the formation of what you now know as HS Tools, which includes a suite of tools you can use for your Hopscotch projects. All of this – the filter checker, web explorer, project builder – all came into existence since after I started hosting my site on GitHub.
  • "I’ve literally never used GitHub before, and I’m still lost"
    • No worries. The first thing you can do is ask questions on what you find confusing in my guide. Is there a certain concept that confuses you? What about this step or that step?
    • It’s ok. That’s why I wrote this – both to explain the basics and to start a conversation in the community on how to get your site running
    • Don’t fret. once you rinse and repeat a few times, you’ll start to understand a little bit more about it. You’ll eventually dig into tracking changes in GitHub, how it’s a resource for you to share code, etc. etc. No one said it would be easy in the beginning, but it is totally worth it
    • We’re in the same boat. Before my site, I’ve never used GitHub before either, and I don’t remember receiving assistance with setting it up. I certainly do hope, however, that this guide helps you in getting that first step. After that, you’ll be making changes left and right, and making the next big tool that revolutionizes the way we think about Hopscotch!
  • "I have the website hosted. Now I just need to learn some HTML and CSS to make it look better. How can I do that?"
    • There are some more tutorials here by other Hopscotchers that will get you one step further
  • "Can I do this from my iPad?"
    • Yes, you can. However, it is harder to find the right tools to make the development easier. Typically the best ones are paid apps from the App Store, and their functionality is still less than that of desktop IDEs.
    • I haven’t tried it myself because I have access to a computer, but if anyone want to try it and add their own mini-guide on here, I’d be happy to link it in the FAQ
15 Likes

Great tutorial! :D

If you’re stuck from here and you want to learn more, there are some great resources on the web! W3Schools has a great HTML starting tutorial you can start with: HTML Tutorial

If you want your site to look pretty after coding the HTML, you can look into CSS: CSS Tutorial


It’s also worth mentioning that if you’re using VS Code, there’s a really handy extension called Live Server which works just like the Python Server with auto reloading, but it’s supported right out of the box as an Extension!


If you’re looking to make a website, I hope you have a lot of fun making it! :grin:

13 Likes

I love this! I’ll be using this soon! Thank you!

4 Likes

awesome topic, Awesome_A!

4 Likes

Nice work!

4 Likes

@Rawrbear that’s a good recommendation, actually. Never used it myself – auto reload can be nice, but sometimes it’s not for me (when I mess with inspect and need to save/copy styles). Not sure if one terminal command or an extension is easier, but I just went with one copy and paste (given there’s Python installed, but installing software shouldn’t be anything new)

For anyone that doesn’t know what a development server is, it’s not as scary as it sounds :slight_smile:

A development server is just one command (which is in the first post) that serves static files on your local machine. Helps a lot with the filesystem and URL paths.

No problem. Glad I could help!

Awesome reply, outer panda

Thanks!

9 Likes

Also, if you’re confused on how to install Live Server, just go to your Extensions tab and search “Live Server”, then choose the first one on the list:

Very valid! Messing with styles within the browser can definitely be useful. Personally, I love using it for rapidly developing sites without having to manually reload all the time.

7 Likes

I’m making a css example

maybe it might be and Awesomer reply lol

3 Likes

Indeed. I love the convenience of auto-reload as well. There’s no wrong approach when it comes to this.

3 Likes

I can’t see it here:

3 Likes

In your screenshot, it says: “You must first add content to your repository before you can publish a GitHub pages site

Curious – did you start with a README? I think if you have a README it would work.

Regardless though, you can just come back to that after following the rest of the guide. Once you get to the step after pushing your files to GitHub, you can revisit that setting and it should let you choose main.

5 Likes

awesome tutorial E, gonna be super helpful for a ton of people :))

5 Likes

Where is the README thing?

3 Likes

If you checked the option when you made the repo, it would be there. But it seems like you haven’t. In that case, it’ll still work, just later.


I like how the first post is still longer than all of the other posts combined :joy:

5 Likes

Okay, thanks E
Should I look like this:

2 Likes

Looks great! Now you can wait a couple of minutes, and it should tell you when the site’s up and hosted when you go to Settings > Pages. :)

If you add an index.html, it’ll replace the README with what you have on there, though!

5 Likes

Very nice topic! Sadly GitHub doesn’t work for me so I had to code my own website. Nice tutorial for those who need it though!

1 Like

What why??

1 Like

google fonts are allowed right?

2 Likes