Using Jekyll to blog in Windows

Background

When I was teenager, I started blogging using Sina. It is a simple blog-publishing service with some customizable options. That was more than enough for a newbie who only knew some HTML and CSS. As time passed by, there is rumour that Sina was going to close its blog service. Therefore, I migrated my blog to Blogger. Blogger provides more customizable options. Other than CSS, you can use widgets. However, I was frustrated by the limited widgets and themes are not enough for me after a period of time.

Then, I found WordPress. It is very powerful but also very difficult to setup. Back then I only knew little about managing a server. After using WordPress for sometime, I notice there was a performance drop on my blog compare to Blogger because I used a cheap VPS.

As my programming skill progress, I wanted to start a blog about programming. WordPress is overkill and I did not want to pay for another VPS or share the VPS with my current blog. I started to search for alternative. Then, I found Jekyll.

Jekyll…?

Jekyll is static site generator. Compare to Blogger and WordPress, they are dynamic website. When a browser request a page, the web server looks up the content from database and combines it with template to deliver to the browser. On the other hand, Jekyll generate all the HTML files and then deploy them to web server. When a browser request a page, the web server serve the page requested. Because there is no query to database and computing, a static site performs much better especially in low-end server.

Then, why not all the website are static site? It is because it cannot have any dynamic functions like login, comment and edit without third party plugin or regenerate the site. But other than that, Jekyll is usually more than enough for users just blogging and want to have their own website with good performance. Also, GitHub and GitLab can host Jekyll site for free!

Environment

There are several ways to host your your Jekyll. Basically, there are two categories: build locally or build on server. Building local having some benefits. You only need to deploy a static website which is just uploading files to your host and you do not have to config the server if you use your only server. Building on server can ignore all the setup if you use GitHub or GitLab.

Choosing hosts

But how can you choose? Let’s look at the host first.

GitHub GitLab Self Host
Cost Free Free Money
Cloud Build Yes Yes Require Setup
Setup No No Yes
Performance Good Poor Depends
Gems Limited (Cloud Build) Unlimited Unlimited
Storage Limited Limited Depends
Bandwidth Limited Limited Depends
SSL Yes Yes Require Setup

GitLab is pretty good but the performance is a serious problem. Sometimes it also feels heavy on the own site. GitHub is also good but due to security reasons to allow use only on some gems. (GitLab is probably using Ruby in Docker on their shared runner to contain the
Ruby program.) You can work around by build the Jekyll site locally and push the generated site to GitHub install.

This tutorial will teach you how to setup your local environment and host it on GitHub or GitLab. If you want to hosts on your server, it should be quite easy for you to find out how.

Preparation

This part is only needed if you want to generate the site locally.

To build a Jeklly site, you need Ruby. To install Ruby in Windows, you can use Ruby Installer. Remember the installation path should not have any spaces and add the folder to PATH. If you have the following error, please follow the instructions here.

 SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

After you have installed Ruby, open Command Prompt. You should follow the instructions here to install DevKit. DevKit is necessary for Sass which is needed for Jekyll.
Enter the following commands.

 $ gem install jekyll bundler

You install Jekyll and Bundler. Bundler is not necessary but it can install all the dependencies for you. You can create a template site by the following command.

$ cd <site-parent-folder>
$ jekyll new <site-folder>

Configure Template

If you do not create a template site from the previous part, you can download a template from others.

For basic usage, you should check out Jekyll Guide. The idea is like PHP which you extract common layout part. Jekyll generates HTML files with the variables fill in. The syntax used by Jekyll is [Liquid] https://github.com/Shopify/liquid/wiki/Liquid-for-Designers).
For example, here is how to list all the post with links.

{% for post in site.posts %}
<a href="{{ post.url }}"><h1>{{ post.title }}</h1></a>
{% endfor %}

It generates result like this.

<a href="/2016/post1"><h1>title1</h1></a>
<a href="/2016/post1"><h1>title2</h1></a>
<a href="/2016/post3"><h1>title3</h1></a>

Write Post

You can write post in markdown, Html and Liquid. The post should be put in the _post folder. Every post requires front matter.

Build

This part only for people have setup local environment

If this is the first time build or you have updated the gems, you have to run the following commands.

$ cd <site-folder>
$ bundler install

The following command will build your site in _site folder and use one of your port as a temporarily web server. You use your browser to see the outcome. Use Ctrl + C to terminate the temporarily web server.

$ jekyll serve

Deploy

If it is a user / organization page then you should have a repository named as .github.io on GitHub or .gitlab.io on GitLab. The content should be push to master branch. If it is repository page, you should push it to any branch on GitHub and GitLab. GitHub require to set to specific branch in settings;GitLab uses .gitlab-ci.yml to copy the files.

Local Build

You just upload all the files inside _site folder or git push to GitHub or GitLab. If you are using GitLab, then you need to add a .gitlab-ci.yml file.

pages:
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    # Only content in public folder will be host
    - public
  only:
  # This script is only affecting the master branch
  - master

Cloud Build

You git push your repository like normal. Remember that _site folder and .sass-cache should be excluded.
Here is a .gitignore example.

_site
.sass-cache
.jekyll-metadata
.asset-cache

If you are using GitHub, you need to edit your Gemfile.

# Comment this line by add # at front
# gem "jekyll", "3.3.0"

# Uncomment the line below
gem "github-pages", group: :jekyll_plugins

If you are using GitLab, you need to create a .gitlab-ci.yml file.

image: ruby:2.3
pages:
  stage: deploy
  script:
  - gem install jekyll bundler
  - bundle install
  - jekyll build -d public
  artifacts:
    paths:
    - public
  only:
  - master

Both GitHub and GitLab will then build automatically whenever there is a commit.

What’s next

You should find out how to configure the template and create your own plugin. There may not always be a perfect theme that suits. Then, you should make one your own. Both of these topics may be one of the future articles.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s