How to: package a new (Rubygem) theme for jekyll v.3.2.1

How to package a new theme for Jekyll v.3.2.1 as RubyGem based on the official theme "minima 1.2" by Parker Moore.

I'm not a programmer, i'm not an experienced user of Jekyll, i'm just a hobbiest web development since March 2016

Please be patient with my English is not my native language and I'm not good at explaining things even in my language.

I used this files of "minima theme" as an example

• "minima.gemspec"
• ".gitignore"
• "Rakefile"

Credits and Thanks

This project is made possible by:

• Jekyll v.3.2.1
  • Jekyll Docs | Themes
• Minima v.1.2
• Rubygems

Requirements

• Git & GitHub account optional (free)
• Setup git identity
• Jekyll v.3.2.1
  • Minima v.1.2 (included with Jekyll v.3.2.1)
• Rubygems account (free)

Steps

• Scaffold
• Preview
• Development
• Build
• Usage
• Re-Use

Scaffold

Create a empty repo on GitHub with the same name as theme (e.g. my-theme) optional

Execute jekyll new-theme to create a new theme with the same name as remote repo and enter to folder

~ $ jekyll new-theme my-theme && cd my-theme

~/my-theme $

If ( GitHub.repo == true ) { sync local folder with remote repo } else { only commit changes }

~/my-theme $ git add --all

~/my-theme $ git commit -m "first commit"

~/my-theme $ git remote add origin [email protected]:USER/REPO.git

~/my-theme $ git push -u origin master

Edit my-theme.gemspec and

• replace "homepage" with valid url (e.g. hello.com)
• erase TODO: to "summary"

NOTE: These changes are temporary, they are only required to run bundle

spec.summary       = %q{Write a short summary, because Rubygems requires one.}

spec.homepage      = "https://hello.com"

Execute bundle to install development dependencies

~/my-theme $ bundle

Execute jekyll new to create a new Jekyll project named "example" and enter to project folder

Important!!! named "example" ( later you can change, but for now... )

~/my-theme $ jekyll new example && cd example

~/my-theme/example $

Remove .gitignore inside "example" folder

~/my-theme/example $ rm .gitignore

Find the source files of "minima" and leave the "example" folder

~/my-theme/example $ bundle show minima && cd ..

# returns path
# in my case
#
# /usr/local/lib/ruby/gems/2.3.0/gems/minima-1.2.0/

~/my-theme $

Copy _includes, _layouts and _sass from "minima"

Important!!! Dont forget the dot, the dot is part of the command

~/my-theme $ cp -r /usr/local/lib/ruby/gems/2.3.0/gems/minima-1.2.0/_includes .

~/my-theme $ cp -r /usr/local/lib/ruby/gems/2.3.0/gems/minima-1.2.0/_layouts .

~/my-theme $ cp -r /usr/local/lib/ruby/gems/2.3.0/gems/minima-1.2.0/_sass .

I used the "minima.gemspec" file of "minimal theme" as an example for the next step.

Edit my-theme.gemspec and

• Add spec.metada ( line 13 )
• Replace spec.files ( lines 15-17 )

spec.metadata["plugin_type"] = "theme"

spec.files         = `git ls-files -z`.split("\x0").select do |f|
  f.match(%r{^(_(includes|layouts|sass)/|(LICENSE|README)((\.(txt|md|markdown)|$)))}i)
end

NOTE: spec.files Files and folders to be packaged in the gem

I used the ".gitignore" file of "minimal theme" as an example for the next step.

Add to .gitignore

• example/_site
• .sass-cache
• *.gem

I used the "Rakefile" file of "minimal theme" as an example for the next step.

Download "minima" zip file from GitHub

~/my-theme $ wget https://github.com/jekyll/minima/archive/master.zip

Extract zip file and copy rakefile

Important!!! Dont forget the dot, the dot is part of the command

~/my-theme $ unzip master.zip

# unzip creates minima-master/

~/my-theme $ cp minima-master/Rakefile .

Delete minima-master/ and master.zip

~/my-theme $ rm -r master.zip

~/my-theme $ rm -r minima-master

Preview

Before preview

Rename

• _sass/minima.scss to _sass/my-theme.scss
• _sass/minima/ folder to _sass/my-theme/

Edit

• _sass/my-theme.scss to change "@import partials" to my-theme/base etc...
• example/css/main.scss to change "@import" to my-theme and erase all "Sass variables"
• Rakefile to change "task preview options theme" "minima" to "my-theme" (line 40)
• example/_config.yml to change
  • url: "exmple.com" to url: "" (local config)
  • theme: minima to theme: my-theme
• my-theme.gemspec to complete with data gem
  • spec.version (Semantic Versioning)
  • spec.summary
  • spec.homepage if ( GitHub.repo == false) { valid url }
• example/Gemfile to change gem "minima" to gem "my-theme"

and then execute

~/my-theme $ bundle

~/my-theme $ bundle exec rake preview

# http://localhost:4000

NOTE: $ bundle exec rake preview runs task preview from Rakefile

Rakefile (Script with task similar to jekyll serve --source --destination using example, _layouts, _sass and _includes to build site)

Development

Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

Add plugins

• /example/Gemfile (add gem "name", "version")
• /example/_config.yml (add gems: -name and configs)
• theme-name.gemspec (add spec.add_development_dependency "name", "version")

Save changes

If ( GitHub repo == true ) { commit and push } else { only commit }

~/my-theme $ git add --all

~/my-theme $ git commit -m "Bla bla bla..."

~/my-theme $ git push -u origin master

Important!!! commit changes, my-theme.gemspec reads commited files

When your theme is released, only the files in _layouts, _includes, and _sass tracked with Git will be released.

Build

Before build

• Documenting your theme
• Adding a screenshot
• Edit my-theme.gemspec to complete
  • spec.version (Semantic Versioning)
  • To include example folder, change f.match line to

  f.match(%r{^(_(includes|layouts|sass)/|(example)/|(LICENSE|README)((\.(txt|md|markdown)|$)))}i)

Important!!! commit changes, my-theme.gemspec reads commited files

Build

~/my-theme $ gem build my-theme.gemspec

Publishing your theme

~/my-theme $ gem push my-theme-*.gem

Usage

Create a new Jekyll project

~ $ jekyll new Blog

Add this line to Gemfile

gem "my-theme"

Add this line to _config.yml

theme: my-theme

Add this line to css/main.scss

@import "my-theme";

and then execute

~ $ bundle install

~ $ bundle exec jekyll serve

# http://localhost:4000

(Re)Use

Things to do before Re-Use this scaffold to create and build new theme

If you want to use a different name for the folder "example"

• rename "example" folder
• edit
  • my-theme.gemspec and replace "example" to "new-folder-name" in f.match line
  • Rakefile and replace "example" in task preview options ( source and destination )
  • .gitignore and replace...

New Theme

Before create new theme

• Create a empty repo on GitHub with the same name as theme
• Clone empty repo
• Copy all files inside this repo less .git folder

And then execute

~/my-new-theme $ git add --all

~/my-new-theme $ git commit -m "first commit"

~/my-new-theme $ git push -u origin master

Rename

• my-theme.gemspec to my-new-theme.gemspec
• /_sass/my-theme.scss to my-new-theme.scss
• /_sass/my-theme/ to /my-new-theme/

Edit

• Rakefile (task preview options theme "my-new-theme")
• my-new-theme.gemspec
  • spec.name
  • spec.version
  • spec.summary
  • spec.homepage
• /example/css/main.scss (@import)
• _sass/my-new-theme.scss (@import)
• /example/Gemfile (theme name)
• /example/_config.yml (theme name)

Add pages, documents, data, etc...

Build Theme

Before build new theme Documenting your theme and Adding a screenshot.

Edit

• README.md (Complete info)
• my-new-theme.gemspec (reviewing)
  • spec.name
  • spec.version
  • spec.authors
  • spec.email
  • spec.summary
  • spec.homepage

Important!!! commit changes, my-new-theme.gemspec reads commited files

Build Gem

~/my-new-theme $ gem build my-new-theme.gemspec

~/my-new-theme $ gem push my-new-theme-*.gem