Since I updated the website, the features I am writing about are no longer reflected on this site. If you wish to see a live demo, it can be found at https://t-aevyz.github.io. There you can find the old version of my site, which includes a working demo of what my site attempted to accomplish. Please note that I will not be answering disqus comments.
Why Not To Test Directly On GitHub?
1) Poor End User Experience
By uploading testing content, you are allowing your end users to see content that is not yet finished, which may negatively impact viewing experience. Let’s say that you are rewriting the navigational bar. Whilst you are rewriting the bar, you may accidentally break it, and prevent the module from displaying the correct content. Sure you can revert this using git, but you will wind up negatively impacting a user who is attempting to load your site.
2) Saves Coding Efforts
Hypothetically you could rewrite your site to show only content that has a
published: true tag on it, however this would require you to reprogram multiple sections of your site, such as post lists and pagers. Furthermore, coding these functions are likely to create bugs in your code, which will only take up more and more time, especially considering that Liquid is a hard language to debug. This effort could be saved by simply testing locally.
3) Unclear Git Commit History
Testing online, means you have to upload your posts to GitHub via commits. This will easily clutter your commit history, making navigating it a terrible idea. Also if you are like me and often does not name things correctly when uploading, your history is likely going to end up like this:
Uploading your content means that you are going have to spend time first uploading your commit to GitHub servers. Furthermore you are going to have to wait until GitHub builds your site and then updates itself. This process can take up to 30 seconds per change. While this does not sound like much, if you are trying to learn to use GitHub sites via trial and error, like most of us do, you are going to notice that this process stacks up quite easily. Locally, most changes build in seconds.
I am fairly sure that there are far more reasons, but these should be enough to demonstrate why this is a bad idea. Whilst I shall admit, that I started off pushing all my tests to GitHub, I soon realized how terrible the idea is. Don’t repeat my mistakes, please…
In order to test your site, you will be required to install Jekyll, so that you can build your site locally.
Windows Installation of Jekyll Officially Windows is not supported by Jekyll, but there are ways of installing Ruby regardless. For anyone using Windows 10 with the Anniversary Update, they can use the Bash on Ubuntu on Windows feature, to install Jekyll via
apt (see Linux instructions).
For the other Windows variants, follow this guide or read the documentation page.
Linux and OSx Installation of Jekyll Prerequisites:
- Ruby version 2.0 or higher
- GCC (check if installed by running
gcc -vin your systems command line interface)
- Make (check by running
make -vin your systems command line interface)
Open a Terminal Prompt of your choice and simply type in
gem install jekyll
For more information, simply read the documentation on the Jekyll website.
Running Your Site
Simply open a Terminal Prompt and change the directory to your Website, aka your GitHub project folder. You can change directory by using the
cd <File Path> command. An example of this would be
cd GitProjects/Website/herring-cove. Some operating systems/file browsers allow you to open a Terminal Prompt at a given folder.
When you have opened the directory in your Terminal Prompt, simply type in
bundle exec jekyll serve and wait for your site to be built. Your folder should look like this:
Whilst the server is running, you can access your site at
127.0.0.1:4000. Now if you make any changes, they shall be automatically updated. The Terminal Prompt shall also give you information on any build fails that it encounters, which can help you alleviate the issue. To stop the server, simply press