Setup a redirect on Github Pages
Tags: github, html
Published: 2019-03-25 14:22:33

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:

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

Change directory into the git repository you just cloned.

```bash
cd username.github.io.git
```

## Boilerplate

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

```bash
touch _config.yml
touch index.html 
```

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


```html
<!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/">
```


### _config.yml

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. 

```yaml
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.

```bash
git commit -a -m "initial files"
```

## Publish

```bash
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!