Overview

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, 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 again 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>. GitHub marks repositories named "<your-username>.github.io" as special and and pages deployed under that repository will not be under a subpage.

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, or build your site using whatever other static site generator you want.

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