New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add missing step for gem-based theme conversion #6802

Merged
merged 1 commit into from Feb 26, 2018

Conversation

Projects
None yet
5 participants
@Strangehill
Contributor

Strangehill commented Feb 25, 2018

Theme documentation steps for converting a gem-based theme into 'intrinsic' site files are missing explanation about plugins.

First brought up in jekyll/minima#157

h/t @ashmaroli

@jekyll/documentation

@ashmaroli

needs some corrections..

@@ -3,7 +3,7 @@ title: Themes
permalink: /docs/themes/
---
Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site's content.
Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package up plugins, assets, layouts, includes, and stylesheets in a way that can be overridden by your site's content.

This comment has been minimized.

@ashmaroli

ashmaroli Feb 25, 2018

Member

Theme-gems do not package plugins. The gemspec only specifies gem-based plugins that are then required by Jekyll while loading the theme-gem.
*.rb files in a _plugins directory in the theme-gem will not be loaded whatsoever (as of v3.7.x)

@@ -108,7 +108,33 @@ Suppose you want to get rid of the gem-based theme and convert it to a regular t
To do this, copy the files from the theme gem's directory into your Jekyll site directory. (For example, copy them to `/myblog` if you created your Jekyll site at `/myblog`. See the previous section for details.)
Then remove references to the theme gem in `Gemfile` and configuration. For example, to remove `minima`:
Then you must tell Jekyll about the plugins that were packaged by the theme. You can find these plugins in the theme's gemspec file as runtime dependencies. If you were converting the Minima theme, for example, you might see:

This comment has been minimized.

@ashmaroli

ashmaroli Feb 25, 2018

Member

here as well.. plugins are not packaged by the theme, just referenced to..

- about the plugins that were packaged by the theme. You can find these plugins in the theme's gemspec...
+ about the plugins that are required by the theme. You can find these plugins listed in the theme's gemspec...
@Strangehill

This comment has been minimized.

Contributor

Strangehill commented Feb 25, 2018

Thank you. Correction attempted.

concerns addressed..

@ashmaroli

This comment has been minimized.

Member

ashmaroli commented Feb 25, 2018

```ruby
# ./Gemfile
group :jekyll_plugins do

This comment has been minimized.

@pathawks

pathawks Feb 25, 2018

Member

If using group :jekyll_plugins, the plugins do not need to be added to _config.yml

This comment has been minimized.

@ashmaroli

ashmaroli Feb 25, 2018

Member

Note: GitHub Pages do not require plugins via Bundler. So adding to _config.yml is always better

This comment has been minimized.

@pathawks

pathawks Feb 25, 2018

Member

Could be listed as an either/or.

This comment has been minimized.

@Strangehill

Strangehill Feb 26, 2018

Contributor

I think I understand. I've attempted to incorporate these notes. Please check for accuracy and style.

@pathawks

This comment has been minimized.

Member

pathawks commented Feb 26, 2018

I like this. This does a really good job of explaining what the issue is, and how to work around it.
It goes into sufficient detail as to actually help the user understand what is happening, rather than just providing a series of commands to execute blindly while crossing fingers.
🏆👊

@Strangehill

This comment has been minimized.

Contributor

Strangehill commented Feb 26, 2018

Thanks!

Either way, don't forget to `bundle update`.
However, if you're publishing on GitHub Pages you should update only your `_config.yml` as GitHub Pages doesn't require plugins via Bundler.

This comment has been minimized.

@ashmaroli

ashmaroli Feb 26, 2018

Member

one small correction here:

- GitHub Pages doesn't require plugins
+ GitHub Pages doesn't load plugins

while require is technically correct in Ruby-lingo, the English equivalent 'load' is better suited here

This comment has been minimized.

@Strangehill

Strangehill Feb 26, 2018

Contributor

great. I was concerned about that. Fixed.

@ashmaroli

👍 👍

@DirtyF

DirtyF approved these changes Feb 26, 2018

@DirtyF DirtyF added the themes 🎨 label Feb 26, 2018

@DirtyF

This comment has been minimized.

Member

DirtyF commented Feb 26, 2018

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit bc214d2 into jekyll:master Feb 26, 2018

3 checks passed

WIP ready for review
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment