How to install Jekyll in OSX

Jekyll is now the jewel of the house. The Helen of Troy of my computers. It is the file analysis system I use to create and maintain this blog. If you don't know what Jekyll is, I recommend you read my previous post on the subject so you can understand what Jekyll is, how it works, and its advantages. But if you want to start trying a new way of blogging, then start by installing Jekyll and seeing how it works.

To get everything ready, you need to install a few things first, most of which are mandatory prerequisites to get everything running smoothly. Follow these steps and you'll have everything set up in no time.

Install XCode

Unlike other systems, Jekyll requires a specific installation of programs and modules. The first thing you need to have installed on your Mac is XCode. The best way to install it right now is through the Mac App Store.

Once XCode is installed, it's important to install the command line tools. Since this isn't installed automatically, you need to indicate it in XCode preferences. In the "Downloads" section of the preferences, under the "Components" tab, you'll find packages to install the command line tools. The list will likely include iOS 6.0, iOS 5.1, iOS 5.0, and the Command Line Tools. The installation takes a while, even though it's only downloading 114MB. The process is slow for some reason.

To know if you actually have GCC installed on your Mac, you need to open a Terminal and run this command:

    $ gcc --version

If everything is okay, it should say:

    i686-apple-darwin10-llvm-gcc-4.2 (GCC) 4.2.1

If this message appears, you can proceed with the rest of the installation without any problems.

Install Homebrew

If you don't have Homebrew, it's time to install this package manager. My recommendation is to remove any other package manager you have, such as Ports, to avoid conflicts. Homebrew is wonderful and allows you to install many things without any problems. To install it, run the following command:

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow all the instructions given during the installation. It shouldn't take long. Once Homebrew is installed, you can install things using the command:

  $ brew doctor

And if it says Your system is raring to brew, then you have it installed perfectly. If not, it will say something like:

Optional: Installing Git

The next step is to install Git. Although it's not necessary, it's recommended because it allows us to clone repositories and upload our blog to Github to have a backup copy. Another reason is that the majority of the plugins are on Github, and some CMS to Markdown converters are only available there, so it's convenient to download them with just one command and have them ready.

  $ brew install git

The next step would be to install Ruby. Ruby is a programming language that Jekyll uses, and it's recommended to have it installed. You should install the latest version. If you have Mac OS X Mountain Lion, you'll have version 1.8.7. According to the tutorials I've read, it's recommended to have RVM (Ruby Version Manager) installed on your Mac. This allows you to perform multiple installations of Ruby on the same computer and indicate which one is correct. This way, if you ever need something that only works on an older version, you can do it with RVM. Installing RVM is relatively easy. Open a Terminal and type:

    $ brew tap homebrew/dupes
    $ brew install autoconf automake apple-gcc42 tcl libksba
    $ curl -L https://get.rvm.io | bash -s stable --ruby

Follow the steps, and once you have RVM installed, you can install Ruby. My recommendation is to install version 1.9.2 or higher (I think they're up to 1.9.3 now), and with this, you should be able to run Jekyll without any problems. To do this, before installing Ruby, we need to check if RVM meets the requirements (sometimes you need to install something):

  $ rvm get head

You can install any missing library using the brew install command. If you didn't miss anything, then you can now install Ruby:

  $ rvm install 1.9.3  --with-gcc=clang

Once installed, we need to configure it as the official version of Ruby on our machine:

  $ rvm use 1.9.3 --default

Use the command $ ruby -v to verify that you have officially installed version 1.9.x. If everything is alright, you should see something like ruby 1.9.3p392 (2013-02-22 revision 39386) [x86_64-darwin12.2.0].

Installing Jekyll

The best way to install Jekyll is using RubyGems. If you don't have RubyGems installed, you can check it by running $ gem -v in the Console. If you have it installed, then you should run:

  $ gem install jekyll

Next, install the following gems: directory_watcher, liquid, maruku, and classifier with the gem installer. You may not have the latest gem versions, so it's a good time to run an upgrade of all gems.

  $ sudo gem update --system

Great! Among all the gems, Maruku is one of the gems responsible for interpreting Markdown files. Maruku is not a bad gem, but many prefer RDiscount because of its speed. I also chose this gem. To install RDiscount, we just use RubyGems:

  $ gem install rdiscount

Correcto! This will make every time you run jekyll --server, it will load RDiscount by default when it needs to process Markdown.

Getting started with Jekyll

The important thing to remember about Jekyll is that it is a text parsing engine. It scans a series of documents and folders and converts them using defined templates into HTML pages. In the middle of this process, we can tweak the URLs to be generated, the way to write these documents with Markdown or Textile, and other elements. Now that you have installed Jekyll, the interesting thing would be to create a folder where you can set up a site and dump a suitable document structure.

A typical Jekyll structure looks like this:

  .
  _config.yml
  _includes/
  _layouts/
    default.html
    post.html
  posts/
    2013-03-07-install-jekyll.markdown
    2013-03-26-barcamp-4.textile
  _site
  index.html

_config.yml is the project configuration file. It is used to execute commands automatically every time you start the Jekyll service. You can configure the project 100% inside this file. From stopping the use of Markdown to using a Textile parser, and so on.

It works as follows: there is a function and a state. For example:

  markdown: rdiscount

This option tells Jekyll that we will use Markdown in our project, but we will also use the rdiscount gem to process Markdown files. This is the composition of a _config.yml. Of course, you can check the documentation about this file, which details each option.

Now, to not confuse you too much, create a text file and name it _config.yml. Inside, write the following:

  auto: false
  server: false
  lsi: false
  pygments: true
  markdown: rdiscount
  pygments: true
  permalink: /:year/:month/:day/:title
  paginate: 1
  exclude: ["lib", "blog.rb", "Capfile", "config", "log", "Rakefile", "tmp"]
  destination: public

Note: The above code block was formatted using Markdown code fences, not the Liquid.

Part of this example is based on my configuration file. You can use it as a guide, but don't use everything because it may give you an error when loading Jekyll. The important thing in this example is that it will basically create a /public/ folder where the processed .html files will be placed with a practical HTML structure in the style of /year/month/day/title`, so you won't have to worry about configuring Apache or anything. In future articles, we will discuss several ways to achieve the same results and learn more things.

Once you have the configuration file, the next important thing has more to do with the folders where the files are stored. We had exemplified some folders before. These folders are read by Jekyll, and some are normative. For example, the _posts/ folder will be investigated to find text files with a specific format. If it finds one, it will analyze it, and from here, it will generate the final HTML result, but the rest of the folders have other predefined functions.

The _layouts/ folder will contain your HTML templates. They will serve to define all kinds of templates, from those you use in posts to others, depending on the complexity of the project, of course.

The _includes/ folder will contain the partial files you use in the templates. For example, if you need to make a header, you don't have to repeat the same amount of HTML in each main template. You can make a header.html file that contains the HTML, and then in the template, you write include header.html so that every time Jekyll processes that template, it calls that partial. A good project should be separated so that you can maintain it with less work.

The _plugins/ folder will be used to put our plugins. Plugins are additional functions that we can download from repositories on Github, offering us the possibility to extend the functionality that Jekyll does not have. I use some plugins, but not too many. There are already a few available, and installation is simple. You just drop a file into the folder and call it from _config.yml. That simple.

Finally, we have index.html, which will currently be the entry template for the blog or site. Like in WordPress, this template has a loop with which you can pull out the posts.

Those were all the folders the project needs. Now, let's make a test entry to see the results of our installation.

Writing in Jekyll

Jekyll, as a parser, requires strictness when writing entries for your blog. You have to respect a certain structure. But don't be afraid: it's not complicated. The first thing we have to learn is how to compose a post. And for that, we'll do a quick tutorial.

Open a text editor and start by writing the header of the blog post:

  ---
  title: My new post
  date: 2013-03-15
  slug: my-new-post
  ---

  Here goes my *new* post

That's the header of each entry. Below the dashes, you write your post using Markdown. Save the file logically, as it should be: first the date, then the title. This entry is named like this:

  2013-03-07-como-instalar-jekyll-en-osx.md

It's important to have this right because otherwise there will be problems generating the blog later. Now what you have to do to generate your blog and see it in action is to run the command $ jekyll --server. Once you have Jekyll running, you will notice that it has created an extra folder called public, which is basically the one we named in the configuration file. You can use any name and regenerate the site, and Jekyll will delete everything and start over. Uploading Changes

The entries are written, the templates are ready, now it's time to upload the blog. There are several methods, automatic and manual. The manual ones are the easiest for those who don't know how to write console scripts. You can simply synchronize your folder with the one you have over FTP so that you don't upload all the files, or you can upload and overwrite everything. The automatic side, running a command that does everything, is more complicated. In addition, you can use other tools beyond a console script. I use a script that does several tasks before uploading everything to my server. The process takes approximately 25 seconds.

With this, I finish the first technical article about Jekyll. In the next one, we will see more topics about templates and configuration to move your blog from WordPress to Jekyll.