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
This project is made possible by:
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 git@github.com: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
Before preview
_sass/minima.scss
to_sass/my-theme.scss
_sass/minima/
folder to_sass/my-theme/
_sass/my-theme.scss
to change "@import partials" tomy-theme/base
etc...example/css/main.scss
to change "@import" tomy-theme
and erase all "Sass variables"Rakefile
to change "task preview options theme""minima"
to"my-theme"
(line 40)example/_config.yml
to changeurl: "exmple.com"
tourl: ""
(local config)theme: minima
totheme: my-theme
my-theme.gemspec
to complete with data gemspec.version
(Semantic Versioning)spec.summary
spec.homepage
if ( GitHub.repo == false) { valid url }
example/Gemfile
to changegem "minima"
togem "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 RakefileRakefile (Script with task similar to
jekyll serve --source --destination
usingexample
,_layouts
,_sass
and_includes
to build site)
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.
/example/Gemfile
(add gem "name", "version")/example/_config.yml
(add gems: -name and configs)theme-name.gemspec
(add spec.add_development_dependency "name", "version")
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.
Before build
- Documenting your theme
- Adding a screenshot
- Edit
my-theme.gemspec
to completespec.version
(Semantic Versioning)- To include
example
folder, changef.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
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
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" inf.match
lineRakefile
and replace "example" in task preview options ( source and destination ).gitignore
and replace...
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
my-theme.gemspec
tomy-new-theme.gemspec
/_sass/my-theme.scss
tomy-new-theme.scss
/_sass/my-theme/
to/my-new-theme/
Rakefile
(taskpreview
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...
Before build new theme Documenting your theme and Adding a screenshot.
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
~/my-new-theme $ gem build my-new-theme.gemspec
~/my-new-theme $ gem push my-new-theme-*.gem