Stephen BelovarichThere 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
Boilerplate
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
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/">
_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.
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"
Publish
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!
