Local Plugins and Pages Missing When Building Custom Theme Gem


I’m experiencing some trouble creating a custom jekyll theme I want to release as a gem:

               │           │
               │  Custom   │  Contains some:
               │  Jekyll   │   - Pages
               │  Theme    │   - Local plugins
               │           │
                     │ Import
               │           │
               │  End_User │  Error:
               │  Jekyll   │   - Missing Pages
               │   Site    │   - Local Plugins not working
               │           │

When I set the gem as the theme for another project, everything works fine except:

  • local plugins from the custom theme’s _plugins directory don’t run on the end user’s site.
  • pages from the custom theme don’t show up in the end user’s site.
    • (it makes no difference if the pages are at the root level – jekyll’s default – or in a specified _pages directory…They all error out with 404).

If I run $ gem contents on the custom jekyll theme’s gem, the files are all there.

Any ideas? 🤷

Many thanks. :pray:

PS Also, external dependencies seem to work fine – e.g. Gems added in the .gemspec are functioning properly.

[Update] If I manually set the _plugins/ path in the end user’s config to the path of the custom theme gem’s _plugins/ dir (/opt/homebrew/lib/ruby/gems/3.0.0/gems/custom-theme-gem-0.0.1/_plugins/), I start making progress – but this is not an ideal solution…Still chugging…:steam_locomotive:

You should not expect pages to be bundled in a theme. The user needs to have control over all the pages themselves.

Layouts in a theme - yes. For example if you want to provide a contact page, create a contact.html layout to be used by the end user if they want.

Regarding plugins. Check the rule in your gemspec file to ensure that the plugins directory gets bundled. And then inspect the installed theme in the site to see that it has a plugins directory.

1 Like

Thanks for the response! :pray:

Re: pages

Hmm…Good to know. Does this also apply to the site index?

And am I missing this in the documentation somewhere? I would be happy to add it if it’s not.

Re: local plugins

My spec.files looks like this currently (which includes those pesky pages):

spec.files         = `git ls-files -z`.split("\x0").select do |f| 

And if I run $ gem contents on the custom theme gem, the expected _plugins/ are all there. So, the files are definitely being added, but for whatever reason the end-user usage of the theme is not scanning the local plugins in the theme by default. But if I explicitly add the _plugins dir in the end-user configs jekyll is somehow forced to finally see the custom-theme-gem-local-plugins:

# in end user's _config.yml
plugins_dir: "/opt/homebrew/lib/ruby/gems/3.0.0/gems/custom-theme-0.0.1/_plugins/"

Any ideas about that one? :thinking:
(I’m hoping I just have a setting wrong, or something)

Thanks again for the tips – esp. about pages. :page_facing_up:

1 Like


From the docs:

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.

Since pages and plugins are both not mentioned, I’m thinking plugins – like pages – just aren’t handled for custom theme gems.

Also, since Jekyll::PluginManager.conscientious_require only looks for plugin files once, that might be the source of the issue…Meaning jekyll just doesn’t support plugins in custom theme gems.

At least, if I am understanding this all correctly.

1 Like

Yes, agree that the docs say what a theme is for and omit “pages” so no update is needed to the docs.

I’ve never tried to run _plugins of a theme in my site, so don’t know if that is supported.

1 Like