DevNotes

Concise, Handy and Elegant Notes for Developers

0%

Set up websites using GitHub Pages

Posted on Edited on In Disqus:

GitHub supports hosting static websites for free. Here we go through the essential steps.

Configure your own website

Firstly, create a new repository from GitHub website, name it username.github.io, the username must match your GitHub account name exactly. Then, clone the repo and add a file index.html, add some texts into it, commit and push back. (This also applies to GitHub organization account.)

1
2
3
4
5
6
git clone https://github.com/username/username.github.io
cd username.github.io
echo "Hello World" > index.html
git add --all
git commit -m "Init"
git push -u origin master

Head back to the repo on GitHub in your browser, from Settings tab, scroll to GitHub Pages section, it will display something like:

Your site is ready to be published at https://username.github.io/.

Great! Now your website is up and running now! And yes, it is ugly, therefore, you probably want to pick one from the static Site generators. There is another post going through the steps to generate sites using Hexo.

Customize domain

Go to Settings -> GitHub Pages to add a custom domain, e.g. www.example.com, and press Save. A file called CNAME will be automatically created at the root of the repository and contains the domain you have given. Now go to your DNS provider, add CNAME record, set Host to www and Value to username.github.io., After done this www subdomain configuration, we continue to add A or ALIAS or ANAME record for apex domain, set Host to @ and point Value to

1
2
3
4
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

So that, example.com will redirect to www.example.com

Project Pages

For GithHub project page, there is no constraints for the repo name, any name works fine. And as long as there is an index.html in the root of the master branch, you can choose to host it from Settings -> GitHub Pages, then it will render the page properly. You can add some javascript and css files to polish the page, here is an example FYR. Similarly, you can just commit a docs folder to the repo and add a text or pdf file into it, and switch to master branch /docs folder to make it show up. Furthermore, using a static site generator to create more advanced website would be more fun and future steps.

Redirect existing site

In case you already have an existing site up and running somewhere else, assuming it’s named example.com. It is possible to redirect your GitHub site username.github.io to point to it if you wish. Just add the code below into your index.html

1
2
3
4
5
<!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/">

Learn more from the references in the bottom.

References:

  • https://pages.github.com/
  • https://help.github.com/en/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site
  • https://dev.to/steveblue/setup-a-redirect-on-github-pages-1ok7
  • https://www.w3.org/TR/WCAG20-TECHS/H76.html