Workflow developing custom theme

Help
1

Hello,

After doing a lot of trial and error, i think found a solution how editing a custom theme without manually restart the Jekyll server again and again and…

So my workflow:

$jekyll new-theme jekyll-theme-custom

$gem build jekyll-theme-milligram.gemspec

Navigate to the Gemfile in my Jekyll-website and adding this line:
gem "jekyll-theme-custom", :path => "/home/ubuntu/themes/jekyll-theme-custom/"

After that type:
$bundle

Then copy all this dirs to the root of my Jekyll-website:
_sass/
_includes/
_layouts/
assets/

Typing:
$bundle exec jekyll serve --watch

When develop themes code in …/website/_layouts , …/website/_includes, … now it change automatically when refreshing the browser.

After finish developing the theme, copying back the dirs from Jekyll-website to the themes root dir.

Is this the right workflow? Or is there a better way customize the theme files?

2

The way I like to do it is:

  1. jekyll new-theme just as you have above to init the theme directory.
  2. Edit your .gemspec as necessary
  3. Add your theme files, _layouts, _includes, _sass, assets, etc. to the theme’s root.
  4. Add a Rake file for spinning up development server… more on that in a minute.
  5. Create a folder to test your theme and add sample posts and pages. I like to use /example and drop in various posts and a _config.yml to stress test my themes.
  6. Add Gemfile to /test 
source "https://rubygems.org"

# use local theme gem for testing
gem "jekyll-theme-custom", path: "../"
  1. cd to /example folder and run bundle to install the dependencies.
  2. cd.. back to the theme’s root and run the following Rake task bundle exec rake preview. This will start a Jekyll server and watch for changes made to the theme files in root.

Here’s my theme repo if you want an example. The nice thing with this method compared to what you have above is you don’t need to move files around. You just work on the theme files as you normally would and start the preview Rake task when you want to test it.

When you’re ready to release a gem you can gem build and gem push as you normally would to post to Rubygems.

2 Likes
3

Thats a well documented step by step guide building a theme.
Awesome :smiley:

I will try this!!

4

@mmistakes

In theme dir it is also possible typing:
$jekyll serve --watch

What is the difference with Rake?

5

Nothing really. You just need to switch to the /example (or whatever you named the test) directory to issue the jekyll serve command.

Using the Rake task you can do it from the root of your project. It’s a preference thing.
I believe I originally saw this workflow in Jekyll’s default theme, which is where I learned about setting it up this way. But looks like they dropped Rake and use a set of shell scripts now.

1 Like
6

Looking in our Rake-file. It has a lot of settings.
At the moment it is less difficult for me as newbie using the jekyll-commands :slightly_smiling_face:
But maybe i used soon, when it more understandable for me.
First time reading about themes on the Jekyll website https://jekyllrb.com/docs/themes/
i don’t understand a lot, now after testing and read 2-3 times it is better to understand.