Cover image for Setup a redirect on Github Pages

Setup a redirect on Github Pages

steveblue profile image Steve Belovarich Updated on ・3 min read

There are several static site generators and even a cli called gh-pages that enable you to easily publish a Github pages site. Sometimes it can be just as easy to implement a custom html page like in the case of implementing a redirect, but it is easy to forget how when you aren't deploying to Github Pages all the time. There are lots of resources for Github Pages but I couldn't find any tutorials that clearly define the handful of steps necessary to start from scratch and make a redirect, so here we go!

Below are the steps to get an index.html deployed to a user account page on Github Pages. This index.html includes a redirect from where user account pages are hosted at https://username.github.io to another site (https://example.com/).

Replace 'username' with your Github username and https://example.com/ with the url you want the user to redirect to in the below examples.

Setup a new repository

To create a user account page, make a new repository on Github setting the name to username.github.io. It is OK if the repository is blank.

It is also worth noting since this is a user account page, Github pages will pull the content from the root directory on the master branch, as opposed to project or organizational pages which can be configured to use the 'docs' directory as the root, or the root directory in a 'gh-pages' branch.

On your local computer, clone the repo:

git clone https://github.com/username/username.github.io.git

Change directory into the git repository you just cloned.

cd username.github.io.git


Next create all the boilerplate files. Make 2 new files in the root directory: _config.yml and index.html.

touch _config.yml
touch index.html 


This file is the template for the page you want to host at username.github.io. In this example we setup a redirect in the index.html file.

Here are some reasons why you would want to setup a redirect on Github Pages.

  • username.github.io redirects the user to a personal site hosted at a domain
  • project documentation is hosted on Github Pages in another repo and you want username.github.io to redirect there
  • project has moved and you want to redirect the user to a new address

The redirect is accomplished with a <meta> tag. By setting the http-equiv attribute to refresh and the content attribute to 0; URL=https://example.com/ we will redirect the user to 'https://example.com/'.

Improve SEO by telling search engines that both sites are essentially the same with a <link> tag that has a canonical url.

<!DOCTYPE html>
<meta charset="utf-8">
<title>Redirecting to https://example.com/</title>
<meta http-equiv="refresh" content="0; URL=https://example.com/">
<link rel="canonical" href="https://example.com/">


We still need to include configuration in order to build. This config would typically be used with the pre-built templates for Github Pages. This seems awkward since we defined a custom index.html, but nonetheless it is a requirement. This is the step most tutorials leave out.

Edit _config.yml and set the theme to jekyll-theme-cayman.

theme: jekyll-theme-cayman

The theme can alternatively be set in the repository settings page on github.com. Github will update the master branch if you choose to set the theme there.

Commit these changes and push the commit to the master branch.

git commit -a -m "initial files"


git push origin master

It can take up to around 10 minutes for the first deployment to finish, but I have seen Github Pages update almost instantly. If everything goes well your redirect should be live at 'https://username.github.io/'.

Follow me for more tips in the coming weeks!


Editor guide
ginigangadharan profile image

Cool ! Thanks for Sharing.

Btw, any idea how to achieve parameter/url passing as well ?

Expection :
mypage on old github should point to mypage on newsite.com
olduser.github.io/mypage --> newsite.com/mypage


mjbryan10 profile image
Matthew James Bryan

Nice article, thanks for the information!

vjnvisakh profile image
Visakh Vijayan

When I open my github page, I want the index.html to be displayed by default. Without the "index.html" in the URL. How to do that?

andymagill profile image
Andrew Magill

Nice article. I didn't think of adding a canonical link. But why bother using jekyl? Why not just put up a complete html ?

steveblue profile image
Steve Belovarich Author

At the time of writing this you had to set a theme as described using jekyl. It is part of the configuration set my Github. Moral of the story, you somehow need to set a theme even if you don’t use it.