This past weekend I decided to finally learn how to use GitHub Pages and to publish my static website using Jekyll. Please let me know if you find anything wrong with my approach, I'm not a software developer and have only used GitHub very little so far.
It's possible to host your basic website directly from GitHub repository. By default, this must be a public repository, but you can make it private if you upgrade to GitHub Pro account.
Benefits of using GitHub Pages
- use GitHub and git repository for making, tracking and pushing your website changes
- no hosting fees – GitHub Pages are free
- no need to install CMS or blogging software, unless you actually need a blog
- save a copy of your website (no need for your hosting backups)
- pick up and improve your git and GitHub skills as you go!
Project Plan for GitHub Page with Jekyll
- setup a new GitHub repository named greys.github.io (it must match the GitHub username of yours, so if you're UnixGuy on GitHub, your URL will be unixguy.github.io)
- Learn Jekyll basics
- Pick a Jekyll theme, clone it into my local working directory of website repo
- Update the necessary files
- Push website copy onto GitHub
- Once greys.github.io works, update domain name
New GitHub repo
- The repository for GitHub Pages must follow strict naming convention. For a user page (not a project), it must be username.github.io.
- This should be a public repository, unless you have GitHub Pro account. Kind of makes sense for most websites, cause they're meant for public accesso on the Internet. Still, double-check that you don't publish any sensitive information on your Jekyll website!
Usernames wise, f you're UnixGuy on GitHub, your URL will be unixguy.github.io and your repo will be github.com/unixguy/unixguy.github.io)
For instructions, visit the https://help.github.com/en/articles/create-a-repo page.
That's it! My new repo is public and available at the expected URL: https://github.com/greys/greys.github.io.
Learning Jekyll basics
Jekyll is a static website generator written in Ruby. It depends on Ruby packages (gems) and uses bundle package manager.
First, install Jekyll. On my MacBook, I did the following:
$ sudo gem install jekyll bundler
Jekyll Theme: Sustain
After browsing through a bunch of Jekyll themes, I decided on the Sustain theme.
Firstly, I cloned it into a local directory:
greys@maverick:~ $ cd /Users/greys/proj
greys@maverick:~/proj $ git clone https://github.com/jekyller/sustain.git
Now I rename it to proj/gleb.reys.net (just so that I know what project this is):
greys@maverick:~/proj $ mv sustain gleb.reys.net
greys@maverick:~/proj $ cd gleb.reys.net
Jekyll related updates (bundle update will take a while to install required packages and plugins):
greys@maverick:~/proj/gleb.reys.net $ mkdir .bundle
greys@maverick:~/proj/gleb.reys.net $ bundle update
And that's it! We can start Jekyll's local webserver to view the resulting website:
greys@maverick:~/proj/gleb.reys.net $ bundle exec jekyll serve
Configuration file: /Users/greys/Documents/proj/gleb.reys.net/_config.yml
Incremental build: disabled. Enable with --incremental
done in 0.339 seconds.
Auto-regeneration: enabled for '/Users/greys/Documents/proj/gleb.reys.net'
Server address: http://127.0.0.1:3000/sustain//
Server running... press ctrl-c to stop.
After this I can access my page in the local browser – http://127.0.0.1:3000/sustain:
Now it was time to make the updates. For now I just commented out the original values in code:
- fixed colours in static/css/main.css
- updated font to Verdana
- updated default font size to 18px
- updated _layouts/layouts.html to remove the Fork Me on GitHub ribbon (there's still a link to the project at the bottom of resulting page)
- changed projects.html and created a few more pages for my online interests
- updated the _config.yml with my profiles and full name
Pushing changes to GitHub
This is the most fun part. For this tutorial, I actually initialise git repo only here, but in reality I've created it at the very start and had plenty of fun editing and committing changes – I discarded them all cause they're not relevant for this task.
Tidy up git repos
Since we closed git repository of , there's going to be .git directory in our website's project. So it's best to remove it:
greys@maverick:~/proj/gleb.reys.net $ pwd
greys@maverick:~/proj/gleb.reys.net $ rm -rf .git
Now we can proceed with initialising git repo of our own.
First, let's initialise the repository and add files:
$ git init .
Initialized empty Git repository in /Users/greys/Documents/proj/gleb.reys.net/.git/
… let's add all the files:
$ git add -A
… and commit them to git repository:
$ git commit -m "First commit"
Now, let's add the remote repository, the online one from GitHub:
$ git remote add origin https://github.com/greys/greys.github.io
We are ready to push the code:
$ git push --set-upstream origin master
Counting objects: 54, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (49/49), done.
Writing objects: 100% (54/54), 477.84 KiB | 6.29 MiB/s, done.
Total 54 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), done.
* [new branch] master -> master
Branch master set up to track remote branch master from origin.
After a minute or two, your GitHub Pages URL should start serving your website. In my case, http://greys.github.io showed my pages.
Setup custom domain name
Since I'm using gleb.reys.net as the website URL, I need to update it in the GitHub settings for the repository:
- Read https://help.github.com/en/articles/quick-start-setting-up-a-custom-domain
- Visit https://github.com/greys/greys.github.io/settings
- Populate the Custom domain field in under GitHub Pages section
- Update your DNS provider settings (I'm using CloudFlare, can't recommend them enough!): gleb.reys.net is a CNAME pointing to greys.github.io.
- Double-check repo settings. Eventually it should recognise your DNS update and will show you something like this in the GitHub Pages section:
Secure website with HTTPS
This may take a bit, the Enforce HTTPS option is not immediately available:
While you're waiting, here's the action plan:
- Read https://help.github.com/en/articles/securing-your-github-pages-site-with-https
- Visit https://github.com/greys/greys.github.io/settings
- Tick the Enforce HTTPS option under GitHub Pages section
Final website check
This is it! The website should be online and ready – in my case at the https://gleb.reys.net URL. As you can see, it's a secure website served over HTTPS now:
That's it for today. Am really happy with this project!
Give it a try and let me know if you need any help getting this setup.
- Unix Tutorial projects
- Unix Tutorial Project: Centralised RSyslog
- Private repositories on GitHub are now free!