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
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!
Top comments (10)
Thanks for sharing! Well as of 2023, it seems like you don't actually need the
_config.ymlfile anymore for whatever reason.That's good because it was always superfluous for most use cases.
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
thanks
You can use JavaScript instead of
<meta>, then setwindow.location =to whatever you want (including paths, query strings, hashes, etc)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="example.com" it doesn't redirect to it why is it so ?
Github Repo Link:- github.com/DYNAMICMORTAL/SketchWeb...
Website:- dynamicmortal.github.io/SketchWebs...
Nice article, thanks for the information!
Nice article. I didn't think of adding a canonical link. But why bother using jekyl? Why not just put up a complete html ?
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.
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?
This is great -- thank you for posting this!