Installing Jekyll and first use.

Installing Jekyll was a breeze for me. All the prerequisites were in place so installing went without an hitch. The install procedure is documented here.
A tip: before you install Jekyll, first update the existing (Ruby) gems with:

$ sudo gem update

Of course you will need to do this in a terminal window.

Then you can install Jekyll:

$ sudo gem install jekyll

And that was all. Ready to create our first Jekyll project.

Make sure that the command prompt is in a directory where the project directory must be created. However keep in mind that this is the development directory, so don't create it in the place where the website will be placed.

Type the following:

$ jekyll new MyGreatSite 

Then cd to the new directory:

$ cd  MyGreatSite 

Again, that is all you need. Next we start the Jekyll build-in server with:

$ jekyll serve 

Now point your browser of choice to: http://localhost:4000.

You should be rewarded with a website with the looks of the default Jekyll template.

Jekyll Templates

Now, at this point you may want to start hunting for nice looking templates or theme's. But I would suggest that you don't. Downloading templates at this early a stage will complicate things before you are ready for it. At least it did so for me, I almost gave up on Jekyll. Luckily I knew I went too far and I backtracked to just the plain Jekyll install.

Instead I suggest you take the time to learn each of the tools used by Jekyll.

First become familiar with HTML and CSS. It is not necessary imo to go in depth, but you do need a working knowledge. As a free resource http://w3schools.com is hard to beat imo. Note that we will be building a site with HTML and CSS so having a good grip on them will be mandatory. However just to start out a rudimentary knowledge should suffice.

Assuming you are somewhat familiar with HTML and CSS, learn SASS in the SCSS flavour. Read through the documentation at: http://sass-lang.com/documentation/file.SASS_REFERENCE.html. Again, just become familiar with the concept, you will learn the true depths as you go along.

Then take a look at Kramdown, the online resource is at: http://kramdown.gettalong.org/documentation.html. Same rule here, just the skinny of it.

I saved the best for last: Liquid. If you are a programmer, a quick scan of the documentation at https://docs.shopify.com/themes/liquid-documentation/basics will suffice. If you are not a programmer, hmm, then make sure you become familiar with it as it is the real power behind Jekyll. This is what you really need to create your own site template (theme).

With this under your belt it is time to attack the default site head on. Study the workings of it, add a post, add a page. Then start changing the theme itself and implement your own design. That is a lot of work, but you will know exactly how the site works and how the tools interact. Which imo is invaluable.

You could now start looking for a theme (for example at http://jekyllthemes.org). Personally I did not find a suitable theme, and besides I really like the challenge of creating my own.

Besides, there are additional questions that needs to be answered before creating a design or adopting one: which market do you want to reach? Do you need to support as many browsers as possible? or is it acceptable to write for the most recent versions? Can you use javascript or do you want to avoid it? Must it be RWD?

The site I will be creating will be made with HTML5 and CSS3. I will try to avoid Javascript.

More about that design in the next post.

Jekyll, what is it?

Jekyll calls itself "A blog aware static site builder".

OK, so what is a blog aware static site builder?

To be honest I am not quite sure about the "blog aware" yet. But the static site builder is something I can wrap my head around. The main idea is that Jekyll is a transformation engine that takes some input files, processes them, and then spits out the (static) files for the website.

Why "static"?, well because there is no interpreter running on the server to process the files before they are sent on their way to the requesting browser. This makes the site fast. No, it makes the site VERY FAST. My old mac mini that I use as a web server did take its own sweet time in serving up PHP Wordpress content. But serving up the pages from a static site is near instantaneous. Very fast indeed!

But, what with dynamic content? Well, dynamic is overrated... no kidding. Yes some websites must be dynamic. But it turns out we can do an awful lot with static websites that include dynamic functionality from third parties. Often for free. So if we want users to be able to comment on our blogs, that is not really a problem. Just find a suitable service provider. I would hazard a guess that most private users and even small companies (that don't do web-based-business) can do just fine with a static website.

Back to Jekyll. So it processes input files. What input files?

This did take me some time to figure out. I thought that it would take some CSS files, some HTML files and then spit out the site. But I was thinking way... to simplistic. Yes, Jekyll is more than a simple merging of CSS and HTML files. It can do some real transformation along the way. So far I have discovered the following types of transformation.

1) It transforms files written in a Markdown flavour (I use Kramdown) to HTML pages. This is very handy when creating content. It is much quicker to create a post or page in Markdown than it is to create the corresponding HTML. The downside is that you have to learn the Markdown syntax, but that is rather easy, and it does take out the headache of writing every post or page in HTML.

2) It creates CSS from SCSS. If you are a web developer you are already familiar with SASS/SCSS. For us programmers, SASS or SCSS is a way better method to write CSS than CSS itself. It has familiarities with object oriented programming. I find it actually easier to learn CSS via SCSS than learning SCC in itself. But yes, it does mean that you have to learn SCSS as well.

3) It processes layout specifications written in a mix of HTML and Liquid to produce the static HTML pages. Liquid looks like a programming language. It has control statements, loop statements, formatting filters, variables etc. As a programmer it is easy to learn.

Workflow

The complete workflow (assuming the site template is ready) is as follows:

Add a post or page written in Markdown to the site, run the Jekyll build command, copy the generated files to the web server, and ... well nothing. That is all there is. The site has just been updated.

So that was easy. You must provide the editor to create the new post cq page. A plain text editor with syntax colouring for CSS/HTML like TextWrangler or BBEdit comes in handy. Also it is necessary to use the command line in the Terminal. That may feel unfamiliar at first but is no real deal breaker.

Site Template

Building the site template is a little more difficult. This is where real sweat is necessary. IMO it is necessary to be somewhat of a programmer to really love this kind of work. If you are unfamiliar with programming, CSS and HTML (and possibly Javascript) then Jekyll may not be your thing.

But I will write more about this as it is the subject of this blog. More to come...

Disclaimer

Please remember that I am just a (novice) Jekyll user. Any insights that I have I have from using Jekyll. What I write helps me in understanding the tool, but may be incomplete or even wrong in the eye's of the Jekyll developers.