In this post, I will show how did I setup Octopress, and use it to install Jekyll and customize Jekyll-text-them for this site.

Before going further, I assume that you already had Ruby installed on your machine. There are may ways to do that, but I always prefer using RVM because it makes it easy to manage multiple ruby versions and their corresponding gems. So that I can always test to upgrade my applications from one Ruby version to another.

Octopress + Jekyll

Octopress is a Ruby gem used to create a scaffold for a new Jekyll blog. You can find their installation guide on their github page. However, as I mentioned in the previous post, there is an error with the octopress publish feature. So that I cloned the project and fixed it myself, so if you want you can install the gem from my cloned version. There are many guides to install gem from git source, this is an example¹.

Follow the instruction and install the custom gem. However, you can still use the official gem if you don’t care about the publish feature, or you want to update the octopress gem later (this is how i did).

Install official octopress:

$ gem install octopress

Now use Octopress to create the new site.

$ octopress new korstic.site

It will create a new directory korstic.site with the file structure:

$ cd korstic.site
$ ls
404.html  about.md  _config.yml  Gemfile  Gemfile.lock  index.md_ posts  _templates

Add the custom octopress to the end of your Gemfile:

!! /Gemfile
group :development, :test do
    # Custom Octopress
    gem 'octopress', :git => 'https://github.com/khangpn/octopress.git'
end

Update Octopress

$ gem update

Voilà! Now you have your site ready. We can use octopress commands to create posts, drafts, pages ² now.

To make it easy to run the site, I created a run file.

$ vim run

Paste this in the run file:

!! /run
bundle exec jekyll clean
bundle exec jekyll serve -w --drafts --future --unpublished -I

The list of flags of serve command can be found here³.

Make the script executable.

$ chmod +x run

Now we can run the site by the script.

$ ./run
    Configuration file: /home/khang/Work/korstic.site/_config.yml
               Cleaner: Removing /home/khang/Work/korstic.site/_site...
               Cleaner: Removing /home/khang/Work/korstic.site/.jekyll-metadata...
               Cleaner: Removing .sass-cache...
    Configuration file: /home/khang/Work/korstic.site/_config.yml
                Source: /home/khang/Work/korstic.site
           Destination: /home/khang/Work/korstic.site/_site
     Incremental build: enabled
          Generating... 
           Jekyll Feed: Generating feed for posts
                        done in 2.272 seconds.
    /home/khang/.rvm/gems/ruby-2.7.0/gems/pathutil-0.16.2/lib/pathutil.rb:502: warning: Using the last argument as keyword parameters is deprecated
     Auto-regeneration: enabled for '/home/khang/Work/korstic.site'
        Server address: http://127.0.0.1:4000
      Server running... press ctrl-c to stop.

Access the site via http://127.0.0.1:4000. Cool 😎!

Before explaining about the Octpress auto-created structure, we will go quickly through some Jekyll’s definitions to have a good understanding 🙈.

Jekyll Layout

Layout is a Jekyll’s definition⁴. It allows re-using the same design in multiple articles.

When you use Jekyll-text-them, it has multiple pre-defined layouts⁵ that you can directly be used in your articles or through the Octopress’ templates.

If you want to create custom layouts, create _layouts directory and put your layout files there. The layout files contains design element such as html tags, css code, and it must have one line with the {{ content }} snippet.

For example, I created a layout named category.html

!! /_layout/category.html

---
layout: page
articles:
  show_excerpt: true
  show_readmore: true
  show_info: true
---

...some html code above

{{ content }}

...some html code below

Notice that {{ content }} snippet? It is where your article’s content will be placed when it use the layout.

If you create a layout with the same name as the pre-defined one, it will overwrite the pre-definied. You can use this feature to modify pre-definied layout as you want.

Now, lets’ see the Octopress’ auto-generated structure.

_templates/

Template is an Octopress’ definition. When you create a site using Octopress, it will add a _templates directory. In the directory, there are three template files:

draft
page
post

Templates files contain Front Matters which you want to add to corresponding article types.

For example, I only want to display date time in my posts, so I add it to my _templates/post

!! /_templates/post
---
title: 
date: 
---

When we combine it with the theme, we can, for example, set different default cover image for posts, pages, or only set author for posts etc… 😎 cool hah?

404.html

It is very simple. If people access to any bad URLs (because of typos, or the page is no longer available), the webserver will return this. This file is generated by Octopress. It contains a very simple html page. However, because I use Jekyll-text-theme, once it is installed, I can use one of its pre-defined 404 layout for simply creating a beautifully useful 404 page 😆. See below for details about Jekyll-text-theme pre-defined pages.

about.md

Introduction about yourself 😐

index.md

It is the homepage for your blog. As 404, I use Jekyll-text-theme layout name landing for my homepage.

Jekyll-text-theme

Jekyll-text-them has a very nice quick start guide to explain installation methods. In short, you can install the theme either by cloning its github repo⁶, or by installing its gem.

The only difference between installing by github repo and the gem is:

With gem-based themes, some of the site’s directories (such as the assets, _layouts, _includes and _sass directories) are stored in the theme’s gem, hidden from your immediate view. You need add some files in your Jekyll site directory.⁷

You can refer to the /test folder, this is a example with gem-based themes.

So, if you use the gem-based themes, you can copy everything in the /test folder to your blog directory. I used this method, because I think it is cleaner to keep all the libraries (gems) together to manage them in the future.

Put this in your Gemfile

!! /Gemfile
gem "jekyll-text-theme"

Then run bundle install. Go to the /test folder and copy all contents to our blog

_data
_posts
404.html
Gemfile
_config.yml
about.md
archive.html
index.html 

If you don’t copy their _config.yml to your blog directory, the theme will use its default settings. However, anything you put in your own _config.yml, they will overwrite the default settings. I recommend to copy their file because you can visually see all of the theme’s options.

The _posts may be redundant, you don’t need it, you already had it 😃.

The Gemfile is also redundant, the one created by Octopress is better.

Now let’s see what we have just copied.

_config.yml

This is the main config file of Jekyll. This files stores Jekyll’s settings, and any variables you want to share among posts, pages. Note that Jekyll is very flexible in term of configuration. You can config it either in the _config.yml, or in each post’s default front matter. Besides that you can create any files under _data directory to store your custom variables, then you can include them anywhere in site using site.data.<variable_name>.

Jekyll-text-theme also their settings here. For the full customization options, visit their document site. Actually, the best way to learn these options is to use the copied _config.yml and play arounds with it, there are very helpful comments for each option.

Jekyll-text-theme has many feature included which you can config such as Google Analystic, Social accounts… The most interesting one could be the Site Settings, and the Front Matter Defaults⁸. We will see more in the post about creating pages, posts.

_data/

This directory belongs to Jekyll⁹. It is used to store user-defined variables. Once you copy the_data from the /test folder, the directory consists of:

authors.yml
lincenses.yml
locale.yml
navigation.yml
variables.yml

These are configuration files for specific components of the theme.

_data/authors.yml

This contains the information of authors in this blog¹⁰. Because this is my personal blog so I don’t use this file at all. However, in another use-cases, you can create list of authors, and reference them in each post.

_data/licenses.yml

😐 I have nothing to say about this. It kinda defined what kind of copyright lincense of your blog.

_data/locale.yml

Some translations for the UI. I don’t use this as well.

_data/navigation.yml

Items in the menu bar, their URL and their translation.

_data/variables.yml

Other variables used in the page. The theme uses this file to store default value for theme’ settings. I am not sure but I believe that _config.yml overwrites this.

😄 ok it’s enough for today. It is a coincidence however HAPPY VALENTINE everyone 🤭🥰😆!!! And to all of my Vietnamese friends “Mùng 3 tết vui vẻ”.