Did you know that you can navigate the posts by swiping left and right?

Build Jekyll Website from Scratch on Windows

August 25, 2016, August 29, 2016 | Comments

category: TECH
jekyll web

When I decided to open my own website with some basic functions, such as blogging, hosting GitHub projects, Jekyll comes as a natural choice to serve as a static site generator with GitHub pages. However, the sad thing is that I didn’t have any knowledge of web development, hosting that time and my first Jekyll effort is basically a fork of GitHub project Jekyll Now. But working on a project in GitHub directly lacks testing, control and monitoring which pushes me further to dig into Jekyll.

1. Introducing Jekyll and GitHub Pages

Once opening account through GitHub, each account is allowed to have one site hosted directly from GitHub repositories which is called ‘GitHub Pages’. Please go to this site (GitHub Pages) for details.

Jekyll is a simple, blog-aware, static site generator. It uses static html pages so there is no extra requirement to database which makes the loads quite fast. Also, Jekyll is the engine behind GitHub Pages which means people could host sites right from GitHub repositories. Combining them together, it gives people ways of creating sites with fast blogging and project sharing with such benefits: 1). local edit; 2). control testing by running Jekyll; 3). pushing through Git.

After checking the official website of Jekyll, I notice that Windows is not official supported (see: http://jekyllrb.com/docs/windows/). Plus, I have no idea of Ruby. I decide to learn how to set up Jekyll on Windows and record the necessary steps based on my experience as follows.

2. Install Ruby and the Ruby DevKit

Since Jekyll is written by Ruby, you will need to install Ruby and corresponding Ruby DevKit which is a toolkit that makes it easy to build and use native C/C++ extensions such as RDiscount and RedCloth for Ruby on Windows.

(2a). Install Ruby and DevKit Go to this site to install Ruby first. Currently, the latest version of Ruby is 2.3.1.

alt text

After installing Ruby successfully, go ahead to install corresponding DevKit.

alt text

(2b). Bind DevKit to Ruby on Windows
Then I follow the steps here to bind it to Ruby installation in my path.

alt text

3. Install Jekyll

Installing Jekyll is done by the form of a Ruby Gem. To start with, I launch the command line from the Ruby just installed in step 2. First of all, I can check which Gem already exists in the Ruby by:

gem list  
## *** LOCAL GEMS ***
##
## bigdecimal (1.2.8)
## did_you_mean (1.0.0)
## io-console (0.4.5)
## json (1.8.3)
## minitest (5.8.3)
## net-telnet (0.1.1)
## power_assert (0.2.6)
## psych (2.0.17)
## rake (10.4.2)
## rdoc (4.2.1)
## test-unit (3.1.5)

To install Jekyll and its dependencies, enter the following command and wait a few seconds until it is completed finished:

gem install jekyll

gem list
## *** LOCAL GEMS ***
## 
## bigdecimal (1.2.8)
## colorator (1.1.0)
## did_you_mean (1.0.0)
## ffi (1.9.14 x86-mingw32)
## forwardable-extended (2.6.0)
## io-console (0.4.5)
## jekyll (3.2.1)
## jekyll-sass-converter (1.4.0)
## jekyll-watch (1.5.0)
## json (1.8.3)
## kramdown (1.12.0)
## liquid (3.0.6)
## listen (3.0.8)
## mercenary (0.3.6)
## minitest (5.8.3)
## net-telnet (0.1.1)
## pathutil (0.14.0)
## power_assert (0.2.6)
## psych (2.0.17)
## rake (10.4.2)
## rb-fsevent (0.9.7)
## rb-inotify (0.9.7)
## rdoc (4.2.1)
## rouge (1.11.1)
## safe_yaml (1.0.4)
## sass (3.4.22)
## test-unit (3.1.5)

You will see Jekyll has been installed into my local machine with its dependencies, such as kramdown and rouge.

Since I will create my site with Jekyll as the engine and host it on GitHub Pages, it is good to know which versions of Jekyll and its dependencies are supported by GitHub Pages. Here is the link.

4. Create First Jekyll Site

After all the steps above are successfully completed, we can create a simple Jekyll by running the following command:

jekyll new test
## New jekyll site installed in C:/Users/abrah/Documents/GitHub/test.

A new folder under current directory is created with the following basic files/folders:

alt text

With these minimal(default) files and folders, we finish building our first Jekyll site. In order to see this testing site in our local machine, we still need to install the following Gems:

gem install wdm
gem install bundler
bundle install

bundle exec jekyll serve 
##run Jekyll through Ruby

Jekyll has a built-in feature to allow us to keep track of changes. In Windows, you need to install Gem ‘wdm’ to enable this function. Also, suggested by GitHub Pages, Ruby uses the contents of your Gemfile to track site’s dependencies and versions. Here is the content of Gemfile of this test site:

source "https://rubygems.org"
ruby RUBY_VERSION
gem "jekyll", "3.2.1"
gem "minima"

Now, our first Jekyll site is up and running in my local machine:

alt text

5. Include Project into GitHub Pages

Sometimes, people will use GitHub to manage projects by different repositories. And if you want to include each individual project into your GitHub Pages, you can simply change your _config.yml of baseurl and url as follows:

baseurl: "test" # the subpath of your site, e.g. /blog
url: "http://anotherpeak.org/"

In this case, I put the test site create in step 4 under my GitHub Pages: http://anotherpeak.org/test/.


Reference:

(1). Jekyll official website, https://jekyllrb.com/.
(2). GitHub Pages official website, https://pages.github.com/.
(3). Run Jekyll on Windows, http://jekyll-windows.juthilo.com/.
(4). Jekyll on Windows, https://jekyllrb.com/docs/windows/.