Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ashmaroli/jekyll-plus

A gem that simplifies the installation and usage of a Jekyll Site linked to a gem-based Jekyll Theme.
https://github.com/ashmaroli/jekyll-plus

jekyll plugin theme-gem

Last synced: 15 days ago
JSON representation

A gem that simplifies the installation and usage of a Jekyll Site linked to a gem-based Jekyll Theme.

Awesome Lists containing this project

README

        

# JekyllPlus

[![Gem Version](https://img.shields.io/gem/v/jekyll-plus.svg)](https://rubygems.org/gems/jekyll-plus)
[![Build Status](https://img.shields.io/travis/ashmaroli/jekyll-plus/master.svg?label=Build%20Status)][travis]

[travis]: https://travis-ci.org/ashmaroli/jekyll-plus

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](#gem-recommendation).*

## 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.

```sh

$ jekyll+ new-site my blog
# => New jekyll site (titled) My Blog installed in ~/my blog.

```

```sh

$ 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](https://github.com/mmistakes/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**](#gem-recommendation) 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`](https://github.com/ashmaroli/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 run `bundle 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 initiate `bundle install` to install the theme-gem.

* the `--classic` switch will run the `extract-theme` command (described below) and copy the theme's template directories and files to the site's default `source` directory. Additionally, if the theme-gem has included a `_config.yml` within it, it will be copied over too, **replacing the one currently present at `source`.**

* the `--theme` switch will initialize a `Gemfile` and a `_config.yml` with the provided `GEM-NAME`. Additionally, this too will **replace the `_config.yml` at `source` 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.

```sh
$ 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

```sh
bundle exec jekyll+ extract-theme _layouts
```

* Or, to simply *extract* the layouts for posts and pages:

```sh
bundle exec jekyll+ extract-theme _layouts/page.html _layouts/post.html
```

* To *extract* whatever is available under the `assets` directory and the `post.html` layout:

```sh
bundle exec jekyll+ extract-theme assets _layouts/post.html
```

* Any file within the theme-gem can be *extracted* to `source`.

```sh
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`** at `source` with your bundled file. **You just need to make sure that the `theme` 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`](https://github.com/ashmaroli/jekyll-data) plugin if the user decides to `build` their site locally using `jekyll+ build` or `jekyll+ serve`.

* If your theme-gem requires certain *customizable* `data files` to exist at `source`, again, pack in the `_data` directory. It can be easily sent to your user's `source` by having them simply run `jekyll+ extract-theme _data` or `jekyll+ extract _data`. Your theme's documentation may need to instruct the user to use that command.

* Except for `index.html`, files generated by `jekyll+ new-site` do not have the `layout:` 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:

```yaml
defaults:
- scope:
path: ""
type: posts
values:
layout: post
- scope:
path: ""
type: pages
values:
layout: page
```

* `index.html` will take on the values defined for `pages` and hence the `layout` is set to `home` by default.

## Plugins & Patches

* Includes the [`jekyll-data`](https://github.com/ashmaroli/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](https://github.com/ashmaroli/jekyll-plus/blob/master/lib/jekyll-plus.rb#L9-L28).

## 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](http://contributor-covenant.org) code of conduct.

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).