Nowadays, most blogs are powered by Wordpress. I am a Wordpress users too and I have to admit it is really a great for blogs.
As others CMS, Wordpress requires a database and PHP in order to process the dynamic pages server-side.
Jekyll is a static site generator. With it I can generate all my blog pages in on my computer and then publish the entire website on a static hosting server.
I bet you already know what git is.
Ruby is an open source programming language. In order to install it locally, the are convenient ways such as rbenv or rvm.
Make sure to install at least ruby 1.9.3 in order to be compatible with Octopress 3.0 and check with:
> ruby --version
> node --version
Ruby libraries are, almost always, distributed in form of ruby-gems (in short gems).
Bundler provides a consistent environment for ruby projects by tracking and installing the exact gems and versions that are needed. All the gems dependencies are declared in the Gemfile and jekyll websites usually have a Gemfile for the dependencies.
Bundler is a gem itself and to install it (globally in your ruby environment) just type:
gem install bundler
Note: if you are using an old version of rbenv, then you’ll need to run
rbenv rehash in order to be able to start using bundler.
For my first experience with Jekyll I am going with Octopress (a blogging framework based on Jekyll). It is basically Jekyll with a new graphic theme and additional plugins.
To start clone the Octopress source code
git clone git://github.com/imathis/octopress.git octopress and then:
> cd octopress/
bundle install we are downloading all the gems needed to generate the website locally.
A very special gem is rake, a Make-like task-runner implemented in ruby. It is used in Octopress to simplify some development task that are usually performed manually when using a plain Jekyll installation.
For example, I used
bundle exec rake setup_github_pages to publish my local website to github-pages. This task created a source branch for the local Octopress installation and setup a master branch in the _deploy subfolder.
pushed the local octopress installation to the source branch of my github repository.
In order to use the default theme, just type:
[git:source *]> bundle exec rake install
The classic theme has been copied in the source and sass directories.
Also the public folder has been created: it will host my generated pages.
Using rake, just issue:
[git:source *]> bundle exec rake generate
Always using rake, just issue
bundle exec rake deploy.
This is the Jekyll feature I like most: I can version the source code of the website :-)
For the first commit:
[git:source *]> git add .
Since I am using github as hosting solution, I have a source branch containing the source code of the blog, and a master branch (linked to the _deploy subfolder) containing the generated website.
Or at least, restoring the local website on the same computer with a new os installation.
The steps are:
> git clone https://github.com/fsferrara/fsferrara.github.io.git
The procedure is quite the same, except the fact I had to clone the master branch in the _deploy subfolder because I am using github-pages.
My first post is exactly this one you are now reading. As per Jekyll convention it is named in a format like
YYYY-MM-DD-post-title.markdown and it is placed in the source/_posts directory.
Anyway, the new_post rake task simplify the operation of adding a new post. I could have run this:
[git:source]> bundler exec rake new_post["Blogging with Octopress and Jekyll"]
to have the new post file in the source/_posts folder. Additionally, the post file is created with the standard Front Matter:
[git:source]> cat source/_posts/2018-01-05-blogging-with-octopress-and-jekyll.markdown
Front matter is where Jekyll starts to get really cool. Any file that contains a YAML front matter block will be processed by Jekyll as a special file. This block adds meta-data to the file sush as permalink, categories, tags, and so on.
Similar to the post creation, the rake task new_page helps to create new pages.
For the usual about page:
bundle exec rake new_page["about"]. Here are more information about Octopress pages.
The about page usually has a link in the main menu. To add such a link, modify the file
source/_includes/custom/navigation.html to add a new entry.
Jekyll is able to generate and serve the static website locally. Octopress offers the rake task
bundle exec rake preview that starts a web server locally listening at http://localhost:4000/.
This task will also watch for local changes and apply them immediately to the local preview.