Set up websites using GitHub Pages
Tags: github, JAMstack
Published: 2020-04-27 20:17:03

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

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

<!--more-->

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](https://www.staticgen.com/). There is another [post](https://dev.to/chuanjin/setup-my-blog-using-hexo-h44) 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

    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](https://github.com/chuanjin/mqttc) 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`


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