JekyllPlus
JekyllPlus is now a tool that simplifies the installation and usage of a Jekyll Site linked to a gem-based Jekyll Theme. Disclaimer: This plugin works best with gem-based themes that are serve-ready packages.
Installation
Simply run:
$ gem install jekyll-plus
Usage
This gem installs an executable jekyll+
that takes a couple of new commands to enrich the Jekyll experience.
Note: Along with the following commands, all existing Jekyll Commands are available to be used with the executable.
The new additions are :
new-site
jekyll+ new-site -- Creates a custom Jekyll site scaffold in PATH
Usage:
jekyll+ new-site PATH
Options:
--classic Classic Jekyll scaffolding
--theme GEM-NAME Scaffold with a custom gem-based theme
--force Force creation even if PATH already exists
--verbose Output messages while creating
Overview
jekyll+ new-site
is very much like jekyll new
in that it generates a static-site precursor to be processed into an HTML website. But its also very different in the sense that new-site
deviates from Jekyll's no-magic philosophy
A default site generated by new-site
will have the site's title
configured based on the PATH
argument supplied.
$ jekyll+ new-site my blog
# => New jekyll site (titled) My Blog installed in ~/my blog.
$ jekyll+ new-site blogs/summer rain
# => New jekyll site (titled) Summer Rain installed in ~/blogs/summer rain.
If the user has Git installed and configured on their system, another set of keys are automatically defined — name:
and email:
, both of which will now be populated with the corresponding Git credentials.
This auto-populate feature extends to sites generated with --classic
and --theme
switches if the theme-gem doesn't bundle a _config.yml
within it.
--
The --theme
switch is for those who have decided what theme-gem to use with their site.
Simply provide the theme's gem-name
.
e.g. To install a site with the gem-based version of the popular theme Minimal Mistakes, (minimal-mistakes-jekyll
), simply run
$ jekyll+ new-site awesome blog --theme minimal-mistakes-jekyll
If you have an older version of the theme-gem already installed on your system, then though a new site will be immediately installed at ./awesome blog
, with the _config.yml
and Gemfile
already set to use this theme, the downside is that you'll still have to manually download the Minimal-Mistakes-config-file from the theme repo to be serve-ready
But if you have installed the serve-ready version of the theme-gem, then by simply running the command stated above, the new site installed at ./awesome blog
will have the minimum required elements to let you serve and preview the site immediately — a Minimal-Mistakes-config-file that has all the settings for your site and the associated template files.
The data files need not be copied over to the source
unless they need to be customized. Data files within the theme-gem will be read like the remaining template files via the built-in jekyll-data
plugin.
If you dont have any version of the theme installed, then new-site
will automatically run bundle install
and install the latest version available if you're connected to the internet.
--
When the --classic
switch is used, the generated site will contain all the directories expected in a Jekyll installation prior to Jekyll v3.2
The --classic
and --theme
switch can be used together to install a classic-style site with the template files and directories extracted to your source
from the theme-gem.
Key Points:
-
new-site
when passed without the--classic
or the--theme
switch doesn't runbundle install
at the end. -
if either
--classic
or--theme
is used, JekyllPlus will first check if the theme-gem (defaults to "minima") is installed in the system. If not found, then it'll initiatebundle install
to install the theme-gem. -
the
--classic
switch will run theextract-theme
command (described below) and copy the theme's template directories and files to the site's defaultsource
directory. Additionally, if the theme-gem has included a_config.yml
within it, it will be copied over too, replacing the one currently present atsource
. -
the
--theme
switch will initialize aGemfile
and a_config.yml
with the providedGEM-NAME
. Additionally, this too will replace the_config.yml
atsource
if a namesake is present at the root of the theme-gem.
--
extract-theme
jekyll+ extract-theme -- Extract files and directories from theme-gem to source
Alias: extract
Usage:
jekyll+ extract-theme [DIR (or) FILE-PATH]
jekyll+ extract [DIR (or) FILE-PATH]
Options:
--force Force extraction even if file already exists
--list List the contents of the specified [DIR]
--lax Continue extraction process if a file doesn't exist
--quiet Swallow info messages while extracting
--verbose Additional info messages while extracting
extract-theme
or extract
does just one thing — copy files or entire directories from the configured theme-gem to the site's source
directory. You can extract any combination of files and directories within the theme-gem as long as you know their path, relative to the theme-gem.
Example scenario: — Extracting the theme's layouts
- Lets first inspect the contents of the
_layouts
directory.
$ bundle exec jekyll+ extract-theme _layouts --list
# =>
Listing: Contents of '/_layouts' in theme gem...
* /_layouts/default.html
* /_layouts/home.html
* /_layouts/page.html
* /_layouts/post.html
..done
- Now I know what layouts are available. To extract the entire
_layouts
directory
bundle exec jekyll+ extract-theme _layouts
- Or, to simply extract the layouts for posts and pages:
bundle exec jekyll+ extract-theme _layouts/page.html _layouts/post.html
- To extract whatever is available under the
assets
directory and thepost.html
layout:
bundle exec jekyll+ extract-theme assets _layouts/post.html
- Any file within the theme-gem can be extracted to
source
.
bundle exec jekyll+ extract-theme read-me.html
Gem Recommendation
The only functional difference between jekyll new
and jekyll+ new-site
is that the latter's --theme
and --classic
switches revolve around a jekyll theme-gem (either the default theme-gem "minima" or the string passed to --theme
.)
The following are a set of recommendations directed at theme-gem developers to make their themes serve-ready:
-
Serve-ready theme-gems contain all the minimum elements that are required to let the consumer easily preview their site by simply running
bundle exec jekyll+ serve
-
If your theme is dependent on a custom
_config.yml
that declares necessary plugins and other settings, then please don't hesitate from bundling that file within your theme-gem.jekyll+ new-site
will then automatically replace the_config.yml
atsource
with your bundled file. You just need to make sure that thetheme
key is properly defined. -
If your theme-gem requires a set of data files that impart locale-configuration (they seldom require customization), bundle them into the gem. They will be read-in via the included
jekyll-data
plugin if the user decides tobuild
their site locally usingjekyll+ build
orjekyll+ serve
. -
If your theme-gem requires certain customizable
data files
to exist atsource
, again, pack in the_data
directory. It can be easily sent to your user'ssource
by having them simply runjekyll+ extract-theme _data
orjekyll+ extract _data
. Your theme's documentation may need to instruct the user to use that command. -
Except for
index.html
, files generated byjekyll+ new-site
do not have thelayout:
key hard-coded in the FrontMatter and hence one can easily bootstrap a site with a theme-gem provided that the theme-gem's_config.yml
has the Front Matter Defaults defined, for example:
defaults:
- scope:
path: ""
type: posts
values:
layout: post
- scope:
path: ""
type: pages
values:
layout: page
-
index.html
will take on the values defined forpages
and hence thelayout
is set tohome
by default.
Plugins & Patches
- Includes the
jekyll-data
plugin that enables reading of data files and_config.yml
within the theme-gem. - Includes patches to various modules and classes used by
Jekyll
adapted from certain existing pull-requests at their respective repos and will be altered / removed as required in future releases.
For details, please refer this file.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/ashmaroli/jekyll-plus.
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.