I need some help understanding the theme creation process when it comes to gems.
Hypothetical
I create a directory /mytheme inside here I have all the usual Jekyll stuff. a user can use this as is by using it as a template on gh-pages and it works as expected.
I now want to make this into a “gem” for others to use.
- In
/mytheme I do bundle gem jekyll-mytheme (Now I have a new directory in mytheme named jekyll-mytheme)
- In
/jekyll-mytheme I have /lib, /bin, /sig and a few other files I expect.
- Following the Rubygems guide “Creating Your First Gem” leads me to suspect the files to places in
/lib are programmatic files not simple HTML / CSS etc?
- I need to include my basic theme files now that will ship
So do I place all of them in the /jekyll-mytheme root along with the README etc or in lib or what? I understand I need to include the reference to where they will be in s.files but where should I be placing them? Does it matter? As long as I tell s.files where to find them? Or is there a proper methodology to this?
tl;dr Where do I put files I want to ship with my gem?
Hello @leatheresque,
The Rubygems guide is for creating gems composed of Ruby code. Jekyll theme-gems are a different beast altogether.
Converting an existing Jekyll theme into a theme-gem is actually a simple process but slightly confusing for new authors.
As of Jekyll 4.3, the jekyll executable can be used to scaffold a theme-gem from scratch. The executable recognizes a command named new-theme, which takes a mandatory argument, the theme-gem-name. For example, when you run jekyll new-theme foobar, Jekyll creates the directory ./foobar that contains everything expected from a theme-gem. The most important file is the [theme-name].gemspec (i.e. foobar.gemspec).
This file determines the constitution of the built gem.
The regex at spec.files filters the contents of the theme-gem.
Jekyll loads only specific theme-gem directories and files regardless of configuration. They’re _layouts, _includes, _sass and assets. Recent versions of Jekyll also support loading _data and a file _config.yml. Every other top-level folder / file will be ignored.
There are no restrictions on individual filenames though. Your layouts, sass partials or assets can be named whatever you want.
Now since you are familiar with setting up a theme-gem from scratch, let’s move on converting an existing theme into a gem.
Assuming that the folder names are as noted above, you need to just add the [theme-gem-name].gemspec file, a License file and you should be good to go. Since there is no means to generate just a gemspec file, the workaround would be to run jekyll new-theme <...> elsewhere, copy the scaffolded License file and gemspec
file from that location into your theme project directory and make necessary edits.
So after I create a theme I don’t need to use the bundle gem mytheme? just create a gemspec file and push to rubygems? I will play around with the jekyll new-theme command and see how it works. I guess the process of creating a theme outside of a site and then adding it to a site confuses me a bit opposed to creating a site with its theme and then that site is the theme?
I appreciate the response. I just need to understand better and the docs are not really helpful at times.
Correct. That procedure is applicable only for gems of Ruby programs.
No. First you need to create a gemspec (as generated via jekyll new-theme ...), make necessary changes as applicable for your theme, and then when you’re ready to publish your theme (pushing to Rubygems site), you need to first build the gem (same process as in the Rubygems tutorial you looked up) and then push the built gem.
1 Like