{"id":17502041,"url":"https://github.com/ashmaroli/jekyll-plus","last_synced_at":"2026-05-03T06:40:26.864Z","repository":{"id":56878726,"uuid":"72214325","full_name":"ashmaroli/jekyll-plus","owner":"ashmaroli","description":"A gem that simplifies the installation and usage of a Jekyll Site linked to a gem-based Jekyll Theme.","archived":false,"fork":false,"pushed_at":"2017-03-06T05:35:37.000Z","size":86,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-10T21:50:00.130Z","etag":null,"topics":["jekyll","plugin","theme-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashmaroli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-28T14:26:45.000Z","updated_at":"2017-03-03T16:31:14.000Z","dependencies_parsed_at":"2022-08-20T22:30:48.145Z","dependency_job_id":null,"html_url":"https://github.com/ashmaroli/jekyll-plus","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashmaroli%2Fjekyll-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashmaroli","download_url":"https://codeload.github.com/ashmaroli/jekyll-plus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246086338,"owners_count":20721334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jekyll","plugin","theme-gem"],"created_at":"2024-10-19T20:36:24.834Z","updated_at":"2026-05-03T06:40:21.842Z","avatar_url":"https://github.com/ashmaroli.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JekyllPlus\n\n[![Gem Version](https://img.shields.io/gem/v/jekyll-plus.svg)](https://rubygems.org/gems/jekyll-plus)\n[![Build Status](https://img.shields.io/travis/ashmaroli/jekyll-plus/master.svg?label=Build%20Status)][travis]\n\n[travis]: https://travis-ci.org/ashmaroli/jekyll-plus\n\nJekyllPlus is now a tool that simplifies the installation and usage of a Jekyll Site linked to a gem-based Jekyll Theme.\n*Disclaimer: This plugin works best with gem-based themes that are [serve-ready packages](#gem-recommendation).*\n\n\n## Installation\n\nSimply run:\n\n    $ gem install jekyll-plus\n\n\n## Usage\n\nThis gem installs an executable `jekyll+` that takes a couple of new commands to enrich the Jekyll experience.\u003cbr\u003e\n**Note:** Along with the following commands, all existing Jekyll Commands are available to be used with the executable.\u003cbr\u003e\nThe new additions are :\n\n\n### `new-site`\n\n```\njekyll+ new-site -- Creates a custom Jekyll site scaffold in PATH\n\nUsage:\n\n  jekyll+ new-site PATH\n\nOptions:\n          --classic          Classic Jekyll scaffolding\n          --theme GEM-NAME   Scaffold with a custom gem-based theme\n          --force            Force creation even if PATH already exists\n          --verbose          Output messages while creating\n\n```\n\n#### Overview\n\n`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**\n\nA default site generated by `new-site` will have the site's `title` configured based on the `PATH` argument supplied.\n\n```sh\n\n$ jekyll+ new-site my blog\n# =\u003e New jekyll site (titled) My Blog installed in ~/my blog.\n\n```\n\n```sh\n\n$ jekyll+ new-site blogs/summer rain\n# =\u003e New jekyll site (titled) Summer Rain installed in ~/blogs/summer rain.\n\n```\nIf the user has Git installed and configured on their system, another set of keys are automatically defined \u0026mdash; `name:` and `email:`, both of which will now be populated with the corresponding Git credentials.\n\nThis auto-populate feature extends to sites generated with `--classic` and `--theme` switches **if the theme-gem doesn't bundle a `_config.yml` within it**.\n\n--\n\nThe `--theme` switch is for those who have decided what **theme-gem** to use with their site.\u003cbr\u003e\nSimply provide the theme's `gem-name`.\u003cbr\u003e\n  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\n\n    $ jekyll+ new-site awesome blog --theme minimal-mistakes-jekyll\n\nIf 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*\n\nBut 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 \u0026mdash; a Minimal-Mistakes-config-file that has all the settings for your site and the associated template files.\u003cbr\u003e\nThe 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.\n\nIf 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.\n\n--\n\nWhen the `--classic` switch is used, the generated site will contain all the directories expected in a Jekyll installation prior to Jekyll v3.2\u003cbr\u003e\nThe `--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.\n\n\n#### Key Points:\n\n  * `new-site` when passed without the `--classic` or the `--theme` switch doesn't run `bundle install` at the end.\n\n  * 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.\n\n  * 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`.**\n\n  * 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.**\n\n--\n\n### `extract-theme`\n\n```\njekyll+ extract-theme -- Extract files and directories from theme-gem to source\n\nAlias: extract\n\nUsage:\n\n  jekyll+ extract-theme [DIR (or) FILE-PATH]\n  jekyll+ extract [DIR (or) FILE-PATH]\n\nOptions:\n          --force     Force extraction even if file already exists\n          --list      List the contents of the specified [DIR]\n          --lax       Continue extraction process if a file doesn't exist\n          --quiet     Swallow info messages while extracting\n          --verbose   Additional info messages while extracting\n\n```\n`extract-theme` or `extract` does just one thing \u0026mdash; ***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.\n\n**Example scenario: \u0026mdash; Extracting the theme's layouts**\n\n  * Lets first inspect the contents of the `_layouts` directory.\n\n  ```sh\n  $ bundle exec jekyll+ extract-theme _layouts --list\n  # =\u003e\n      Listing: Contents of '/_layouts' in theme gem...\n\n             * /_layouts/default.html\n             * /_layouts/home.html\n             * /_layouts/page.html\n             * /_layouts/post.html\n               ..done\n  ```\n\n  * Now I know what layouts are available. To *extract* the entire `_layouts` directory\n\n  ```sh\n  bundle exec jekyll+ extract-theme _layouts\n  ```\n\n  * Or, to simply *extract* the layouts for posts and pages:\n\n  ```sh\n  bundle exec jekyll+ extract-theme _layouts/page.html _layouts/post.html\n  ```\n\n  * To *extract* whatever is available under the `assets` directory and the `post.html` layout:\n\n  ```sh\n  bundle exec jekyll+ extract-theme assets _layouts/post.html\n  ```\n\n  * Any file within the theme-gem can be *extracted* to `source`.\n\n  ```sh\n  bundle exec jekyll+ extract-theme read-me.html\n  ```\n\n\n## Gem Recommendation\n\nThe 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`.)\n\nThe following are a set of recommendations directed at theme-gem developers to make their themes **serve-ready**:\n\n  * **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`**\n\n  * 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.**\n\n  * 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`.\n\n  * 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.\n\n  * 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:\n\n  ```yaml\n  defaults:\n    - scope:\n        path: \"\"\n        type: posts\n      values:\n        layout: post\n    - scope:\n        path: \"\"\n        type: pages\n      values:\n        layout: page\n  ```\n\n  * `index.html` will take on the values defined for `pages` and hence the `layout` is set to `home` by default.\n\n\n## Plugins \u0026 Patches\n\n  * Includes the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin that enables reading of data files and `_config.yml` within the theme-gem.\n  * 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.  \n  For details, please [refer this file](https://github.com/ashmaroli/jekyll-plus/blob/master/lib/jekyll-plus.rb#L9-L28).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/ashmaroli/jekyll-plus.\u003cbr\u003e\nThis 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.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashmaroli%2Fjekyll-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashmaroli%2Fjekyll-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashmaroli%2Fjekyll-plus/lists"}