Preface
Goal: Bundling theme in Gem, for use with other people.
Source Code
This article use tutor-07 theme. We will create it step by step.
Introduction
This chapter is a little bit different. We are not talking about just Jekyll anymore, but more about Jekyll in Gemfile, and how to use the Gem properly.
What can be bundled?
-
_includes
, and -
_layouts
,
And additionaly
-
assets
, and -
_sass
.
Directory Structure
Now consider make two separate directories:
-
gem
, for theme -
src
, for Jekyll source
Then move both _includes
, and _layouts
to gem
directory.
$ tree -d -L 2
.
├── gem
│ ├── _includes
│ └── _layouts
└── src
├── pages
├── _posts
└── _site
7 directories
It is easier to have directory side by side as above . So you can move from one directory to another, or put something back, whenever there is trouble.
I added MIT LICENSE
file, just for example sake.
1: Build Gemfile
We need to prepare gemspec
, the Ruby Gem specification.
Official Documentation
It is easy to google, this one:
Ruby Gem Specification
Gem::Specification.new do |spec|
spec.name = 'oriclone-plain'
spec.version = '0.1.0'
spec.date = '2020-07-06'
spec.authors = ["E.R. Nurwijayadi"]
spec.email = 'epsi.nurwijayadi@gmail.com'
spec.summary = "Oriclone Plain - Jekyll Theme"
spec.description = "An example of Jekyll Theme without Stylesheet Burden"
spec.homepage = "https://gitlab.com/epsi-rns/tutor-jekyll-plain"
spec.license = "MIT"
require 'rake'
spec.files = Dir.glob("{_layouts,_includes}/**/**/*") +
['LICENSE']
end
The early lines in specification above is just string. The issue comes with files, especially for ruby beginner like me.
Files Specification
How about multiple files in multiple directories?
In a few of article I read in the internet suggest to use git
.
The issue rise, for my tutorial, because I’m not always put files,
in git folder.
spec.files = git ls-files -z.split("\x0")... }
But I finally find a way to glob
,
even though I never see any gem using this method.
require 'rake'
spec.files = Dir.glob("{_layouts,_includes}/**/**/*") +
['LICENSE']
Sorry for my Ruby skill.
Bundle Theme in Gem
Just as the official document said:
$ cd gem
$ gem build oriclone-plain.gemspec
Successfully built RubyGem
Name: oriclone-plain
Version: 0.1.0
File: oriclone-plain-0.1.0.gem
You should see a file named oriclone-plain-0.1.0.gem
pop up,
in directory.
Install Bundled Theme
Now install, the theme we just bundled.
$ gem install ./oriclone-plain-0.1.0.gem
Successfully installed oriclone-plain-0.1.0
Parsing documentation for oriclone-plain-0.1.0
Installing ri documentation for oriclone-plain-0.1.0
Done installing documentation for oriclone-plain after 1 seconds
1 gem installed
Check The Installation.
Now install, the theme we just bundled.
$ ls ~/.rvm/gems/ruby-2.6.5/gems | grep oriclone
oriclone-plain-0.1.0
$ tree -d -L 1 ~/.rvm/gems/ruby-2.6.5/gems/oriclone-plain-0.1.0
/home/epsi/.rvm/gems/ruby-2.6.5/gems/oriclone-plain-0.1.0
├── _includes
└── _layouts
2 directories
Just make sure the theme is there .
I believe we are ready to use the gem theme.
2: Using Gemfile
This require changing in both Gemfile
and _config.yml
.
Gemfile
Now we can get rid of minima
, and use our very own theme.
source "https://rubygems.org"
gem "jekyll", "~> 4.1.1"
# gem "minima", "~> 2.0"
gem "oriclone-plain", "~> 0.1.0"
group :jekyll_plugins do
gem "jekyll-paginate"
# gem "jekyll-paginate-v2"
end
$ bundle install
...
Using jekyll 4.1.1
Using jekyll-paginate 1.1.0
Using oriclone-plain 0.1.0
Bundle complete! 3 Gemfile dependencies, 30 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
Configuration
# Custom Gem Theme
theme: oriclone-plain
Now run jekyll serve
. Your site should working properly.
Just be aware that, not every _includes
or even _layouts
,
should be moved to Gem theme.
For flexibility reason, some shortcodes, or other _includes
,
that tightly closed to content, or assets, or change regularly,
should be better to be placed outside bundle.
Conclusion
We are done with jekyll plain
,
but we still have jekyll
with stylesheet
to cover.
Let’s put on clothes to our plain jekyll,
and make the blog looks fashionable.
The direct chain of this theme bundling article is: either [ Jekyll Bootstrap - CSS Intro ], or [ Jekyll Bulma MD - CSS Intro ].
What is Next?
For now, consider make your site live, and continue later with stylesheet. Consider continue reading [ Jekyll Plain - Deploy - Simple ].
Thank you for reading.