Overview

Prerequisites

Knowledge of Git and a GitHub account

GitHub Pages is a static site hosting service that GitHub offers. As a static site service it can only serve static HTML, CSS, and JavaScript files. However through services and tools like GitHub Actions and Jekyll, an SSG which GitHub pages has native support for, fairly complex and interactive sites can be built. All websites are hosted under a *.github.io subdomain, but custom domain names can be used.

Getting Started

By default GitHub Pages uses Jekyll a static site generator built in Ruby which takes Markdown, HTML, and CSS files and generates a website. Jekyll is great for easily putting together a good looking blog post or generic static websites.

To start all you really have to do is make an index.md file add some content and push it to a GitHub repository. From there head to your repository, and go to Settings > Pages. Keep the Source as Deploy from branch and change Branch to your HEAD branch, usually this is main or master. You can leave the Folder as / (root).

It might take a few minutes to build and deploy your site but it should be available under <your-username>.github.io/<repository-name>.

Tip

GitHub marks repositories named <your-username>.github.io as special and and pages deployed under that repository will not be under a subpage. Instead they will be directly under the URL your repository is named. You can add a CNAME file to the root folder of your repository if you want to use your own domain name.

Using Jekyll

Jekyll gives you a lot of room to customize your website. You can either use templates or "themes" that GitHub provides, find some online, or make your own.

As a simple example, if I wanted to use the Moonwalk Jekyll Theme all I would have to do is create a _config.yml file and add the following lines.

remote_theme: abhinavs/moonwalk
plugins:
- jekyll-remote-theme

However this gives you pretty limited configurability of the theme. I would highly suggest downloading Ruby and Bundler to help you test your website locally and better configure and make your own theme.

You can either find a theme online [1] and follow its instructions for getting started, or start your own theme with a few commands.

cd YOUR-PROJECT
bundle exec jekyll new --skip-bundle # Create a new jekyll site

Then open up the Gemfile and uncomment the line that contains and replace GITHUB-PAGES-VERSION with the most up to date version of github-pages from here

gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins

Then comment out the line that starts with gem "jekyll".

Save and exit the Gemfile and run:

bundle install

Serving Static Files

To disable using Jekyll all you have to do is make an empty file named .nojekyll. From there you can upload whatever static HTML/CSS/JS files you would like to the repository to have them served.

If you want, you can use another SSG framework such as Astro or Next.js with GitHub Pages to generate your site.

Tip

A specific sub-directory can be chosen to deploy from as well. The option will appear when you go to settings to change what branch Pages deploys from.

This can be used by using an SSG to generate your site locally and uploading the build files to your repository.

Resources

  1. https://docs.github.com/en/pages
  2. https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
  3. https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll

  1. I suggest https://jekyllthemes.io/ or https://jekyllthemes.io/ ↩︎