DEV Community

Cover image for Setup a redirect on Github Pages
Steve Belovarich
Steve Belovarich

Posted on • Updated on

Setup a redirect on Github Pages

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 to another site (

Replace 'username' with your Github username and 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 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
Enter fullscreen mode Exit fullscreen mode

Change directory into the git repository you just cloned.

Enter fullscreen mode Exit fullscreen mode


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 
Enter fullscreen mode Exit fullscreen mode


This file is the template for the page you want to host at 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.

  • redirects the user to a personal site hosted at a domain
  • project documentation is hosted on Github Pages in another repo and you want 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= we will redirect the user to ''.

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</title>
<meta http-equiv="refresh" content="0; URL=">
<link rel="canonical" href="">
Enter fullscreen mode Exit fullscreen mode


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
Enter fullscreen mode Exit fullscreen mode

The theme can alternatively be set in the repository settings page on 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"
Enter fullscreen mode Exit fullscreen mode


git push origin master
Enter fullscreen mode Exit fullscreen mode

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 ''.

Follow me for more tips in the coming weeks!

Discussion (6)

ginigangadharan profile image
Gineesh Madapparambath

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 -->


dynamicmortal profile image
Mihir Amin • Edited on

How to redirect a user while clicking on social icons to my social handle id page? I have hosted my page on github but I wrote as
href="" it doesn't redirect to it why is it so ?
Github Repo Link:-


mjbryan10 profile image
Matthew James Bryan

Nice article, thanks for the information!

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 • Edited on

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

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?