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.
Update - Actually I used Octopress for few days. Then I moved to a very similar static site generator: Hexo. Hexo is easier to use and quite compatible with the Jekyll blog format. Additionally, Hexo runs with nodejs :-)
Have a look at the source code with instructions.
Prepare the Jekyll environment
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
ruby 2.4.3p205 (2017-12-14 revision 61247) [x86_64-darwin16]
> 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.
Start a new website
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/
[git:master]> bundle install
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.
Setup an Octopress theme
In order to use the default theme, just type:
[git:source *]> bundle exec rake install
## Copying classic theme into ./source and ./sass
mkdir -p source
cp -r .themes/classic/source/. source
mkdir -p sass
cp -r .themes/classic/sass/. sass
mkdir -p source/_posts
mkdir -p public
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.
Generate the static website
Using rake, just issue:
[git:source *]> bundle exec rake generate
## Generating Site with Jekyll
Configuration file: /opt/home/github/fsferrara/octopress/_config.yml
Auto-regeneration: disabled. Use --watch to enable.
Generate the static website
Always using rake, just issue
bundle exec rake deploy.
Commit the website source
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 .
[git:source +]> git commit -m "my first octopress commit"
[git:source]> git push origin source
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.
Restoring the local website on a new computer
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
> cd fsferrara.github.io
[git:master]> git checkout source
[git:source]> git remote add octopress git://github.com/imathis/octopress.git
[git:source]> git clone https://github.com/fsferrara/fsferrara.github.io.git _deploy
[git:source]> bundle install
[git:source]> bundle exec rake generate
[git:source]> bundle exec rake deploy
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 with Octopress
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"]
mkdir -p source/_posts
Creating new post: source/_posts/2018-01-05-blogging-with-octopress-and-jekyll.markdown
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
title: "Blogging with Octopress and Jekyll"
date: 2018-01-05 23:01:08 +0100
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.
The about page
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.
Preview the changes locally before publishing
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.