Back to Articles

Spin Up Websites Quickly with GitHub Pages

Published 2018-12-02

(I'm not affiliated with GitHub)

I just love using GitHub Pages. I've been advocating others to use GitHub Pages pretty much since it's been a feature. Hosting a basic static website is straightforward, but GitHub Pages repositories make deploying changes a breeze.

What Is It?

GitHub Pages may just seem like a free way to host simple websites, but coolest part is how it's integrated with Git (the version control software) and GitHub's other features (notably GitHub Apps). Those two factors are the biggest differentiator between classic shared hosting and services like GitHub Pages. It's a great alternative to rolling your own server, especially in your projects' prototype phases.

(GitLab has a pretty much identical feature called GitLab Pages if its more your cup o' tea. I personally prefers GitHub's experience)

GitHub Pages settings

What Should I Use It For?

  1. Personal website - For many newer software engineers, there was probably a point in the past where you followed the GitHub Pages tutorial to create your very first personal website. It's almost a rite of passage. Whether you're experienced or not, it's a quick and easy way to set up a web presence.
  2. Repository website - Got a cool open source project? You can use GitHub Pages to set up a demo and/or documentation site. You can use their built-in Jekyll blog setup for a quick and dirty solution or set up something more elaborate.
  3. Prototyping website - If you're working on something that the frontend can be hosted statically, why not just throw it up on GitHub pages? Update your live site as quickly as you can your source code!

Albeit a little lackluster in features in comparison to even a managed webserver (you won't have .htaccess either), it offers a great deal of simplicity and ease-of-use.

I've personally use it for some of my projects:

Usage Rules and Limits

GitHub does impose several rules on what you can do with GitHub Pages, and you can find them here. In short, you have some restriction in size and bandwidth which makes sense since it is a free service.

Oh, and you can't run a commercial business off of it, but hopefully you should be able to afford a small $5 instance at that point.

Quick Feature Recap for GitHub Pages

So, GitHub Pages has a couple ways to host a website.

  1. Preconfigured Jekyll with a few (rather lame) themes

    • I can see how this can be useful for a team/individual who just wants to dump a bunch of Markdown and see a website magically work. In terms of design and technical flexibility, this scores the worst out of all the other ways to use GitHub Pages. Use this if you're interested in dumping your knowledge in Markdown and moving on to other things.
    • If you want to put these Markdown files in the same directory as your code, you can actually drop these in a /docs folder and select it as your source in the Source configuration.
  2. Serve a website from the master or arbitrary branch

    • This is where people usually start when they're building their first website on GitHub Pages. You can write your own HTML, CSS, and JavaScript, but functionally it is no different than dropping these files into a normal managed webserver. If writing pure HTML, CSS, and JavaScript is your vibe and you have no need for web frameworks like React or Vue, then you'd be very happy with this solution.
  3. Serve a website from the gh-pages branch

    • This is like #2, except this allows you to keep your source code and public site separate. It's actually kind of hidden from the settings because it won't show up as a selection in the Source configuration dropdown unless a gh-pages branch exists in your repository. This is great because you can write source files, then push the build output in this branch. This GitHub help page here talks about it in detail.
    • Unfortunately managing a website with this manually is actually a little bit of a pain. However, combined with a continuous deploy tool (which I'll talk about in a later article), you can have source files, set up configurations, use build tools, and deploy your website within just one project repository.

What Kind of Technologies Can I Use?

GitHub Pages sure has its limitations, but with a little creativity you can get a lot of cool stuff hosted on there.

  • Static Pages - These are the Web 1.0 websites you're familiar with. Write HTML, CSS, and JavaScript and see them just like you expect.
  • Statically Generated Websites - You can set up a fully customizable Jekyll, Metalsmith, or Gatsby process and keep your source pages DRY.
  • Single Page Applications - Similar to statically generated websites, you can set up build tools like Webpack, Gulp, or Parcel. With that, you can build basically any of those cool SPAs with fancy frameworks like React or Vue! You may have heard of a server architecture called JAMstack, and you can host your frontend for that on GitHub Pages.


I've encountered two reasons to not use GitHub Pages so far:

  • No Server-Side Rendering - Yeah, you have a dumb static server so you're going to be able to set up any of the niceties from server-side rendering.

    • I think there are other optimizations that can improve performance, like bundle splitting, file optimizations, and lazy loading, before implementing server-side rendering.
    • However, if you're worried about SEO, search engines can crawl HTML5 history API routes, hash routes, and (unrelated) even query strings!
  • Authentication - Again, because you don't have a server, you can't set up authentication thru cookies. However, you can set up a token-based authentication via an internal REST API for your frontend. I haven't found a library that made this easier yet, so it is a little involved to set up.

Up Next

I want elaborate on JAMstack and why I think it's a great way to build frontend-heavy projects. I also found that using the gh-pages branch feature entirely with Git is pretty involved and is best used with a continuous deployment tool.

I'll leave these two points for a later post, but I hope you learned more about GitHub Pages and will think about taking advantage of it in the future if it makes sense!