Creating and publishing a Jekyll theme

This has nothing to do with Swift. But I maintain a couple of websites that I have all switched from Wordpress to Jekyll. There must be a Jekyll theme out there that I could use, but I didn't find it. So I build my own. And to make sure that it remains available as well as maintainable I thought to enforce a bit of quality by making the theme public. It is available for download from RubyGems under the name: Classic-Jekyll-Theme.

As usual many "howtoes" on the net don't detail all steps or skip a little background know-how that would make things easier. So I created my own. As a result the procedure I describe here may not be the most efficient way. But it did (does) work for me!

First: Create a new Jekyll theme.

(btw: almost all commands will be given from a terminal window, so go ahead an open one up. And while you are at it, maybe also do a quick update of all gems?)

$ jekyll new-theme my-theme

Btw: I use all low-caps to avoid any problems with camel-case and case-sensitive file systems. (Ask me why - no don't!)

The difference between this theme and "normal" themes is that it won't try to look up anything from the ruby gems directory.

Change to the new directory:

$ cd my-theme

Since this is a new theme it cannot be started with "jekyll serve" but we need the "bundler" gem to create the environment for "jekyll serve" to execute in. If you don't have the "bundler" gem installed, do so now:

$ sudo gem install bundler

If we now try to start the theme with "bundle exec jekyll serve" then it will report an error because the gemspec has not been properly defined. Do that by editing the "my-theme.gemspec" file.

There are 2 TODO's in that file that must be fixed. The spec.summary and the spec.homepage. Later on when we create updates of the theme we need to update spec.version each time a new release is created. If the gem will be hosted on rubygems.org, we can set the spec.homepage to "https://rubygems.org/gems/my-theme".

Next, simply try to run the jekyll server:

$ bundle exec jekyll serve

Point a web browser to "localhost:4000" and see what happens. If everything went fine there should be something like this:

Index of /

 Name                          Last modified         Size

 Parent Directory              2016/11/17 08:56      -
 Gemfile                       2016/11/17 08:51      38
 Gemfile.lock                  2016/11/17 08:55      1120
 LICENSE.txt                   2016/11/17 08:51      1071
 README.md                     2016/11/17 08:51      1885
 my-theme.gemspec              2016/11/17 08:55      666

---

WEBrick/1.3.1 (Ruby/2.0.0/2015-12-16)
at localhost:4000

So far so good. But we would like to see a website there. Obviously there is some stuff missing that is needed to create a working site. For example an index.html ;-)

Create a file called "index.md" with the following content:

---
# You don't need to edit this file, it's empty on purpose.
# Edit theme's home layout instead if you wanna make some changes
# See: https://jekyllrb.com/docs/themes/#overriding-theme-defaults
layout: home
---

Hello World!

Save it and start the jekyll server if it was not running:

$ bundle exec jekyll serve

Check the browser, refresh or load the site at: "localhost:4000".

Lo and behold: "Hello world!" is what we should see.

We can now start developing our theme.

Once theme development is done, we might want to publish our theme on RubyGems.

(CTRL-C to stop the Jekyll server)

To do so, we need to build the gem and push it to the rubygems site. An account is needed for that, so register at the site and log in. There is no need to stay logged in though. Once logged-in everything should be set up so we can upload (push) the gem when ready.

When jekyll created the new theme it also set up a git repository. That repository is used when creating a gem. So when the gem is ready:

- Update the README.md so that other people can find out the where and how of the theme.
- Update the release number in the gemspec.
- Then (assuming you are still in the directory my-theme):

$ git add .

Note: I like to use "git status" here to verify that the only expected files are ready for commit

$ git commit -m "reason for commit"
$ git tag 0.1.0

The version number should match the version number in the gemspec. However this is not needed to create the gem, it is four our own reference)

$ gem build my-theme.gemspec
$ gem push my-theme-0.1.0.gem

And that is all. To create a new version of the theme, repeat the last few steps from "update the README.md".

Happy coding...

If you like to thank me, I'd gladly accept a cup of coffee. You can do so by clicking this
link: a cup of coffee ($2) or use the popup on the right hand side for different amounts.
Payments will be processed by PayPal, receiver will be sales at balancingrock dot nl
Bitcoins will be gladly accepted at: 1GacSREBxPy1yskLMc9de2nofNv2SNdwqH