5.1 KiB
title | last_modified_at | categories | tags | toc | toc_label | ||
---|---|---|---|---|---|---|---|
Gemified Theme -- Alpha Release | 2018-03-20T16:00:58-04:00 |
|
|
true | Getting Started |
Jekyll themes distributed as Ruby gems are finally here to make installing and upgrading much easier. Gone are the days of forking a repo just to "install it". Or dealing with merge conflicts when pulling in upstream commits to "upgrade it".
If you're interested in testing out Minimal Mistakes as a gemified theme read on. There are a few caveats though:
- Support for a theme
assets
folder was recently added to Jekyll core, but has yet to be released or rolled into thegithub-pages
gem. Meaning you can't use Minimal Mistakes as a Ruby gem there just yet... locally served or self-hosted installs should be fine if you don't mind using a pre-release version of Jekyll. - Windows users can't currently use themes packaged as gems due to a bug with file paths in Jekyll core. This is being worked on so hopefully a fix is on the way soon.
Fine with all that? Great. Let's continue.
If you're migrating a site already using Minimal Mistakes and haven't customized any of the _includes
, _layouts
, _sass
partials, or assets
this should be quick and painless.
Step 1: Remove Theme Files
Remove _includes
, _layouts
, _sass
, assets
folders and files within. You won't need these anymore as they're bundled in the theme.
If you customized any of these then leave them alone and only remove the untouched ones. If setup correctly your modified versions should act as overrides to the versions bundled with the theme.
Step 2: Update Gemfile
In order to test you'll need to install pre-release gems of Jekyll and Minimal Mistakes.
Start by replacing gem "github-pages"
or gem "jekyll"
with the following:
gem "jekyll", :git => "https://github.com/jekyll/jekyll.git"
Then add the pre-release Minimal Mistakes theme gem:
gem "minimal-mistakes-jekyll", :git => "https://github.com/mmistakes/minimal-mistakes.git", :branch => "feature/theme-gem"`
When finished your Gemfile
should look something like this:
source "https://rubygems.org"
gem "jekyll", :git => "https://github.com/jekyll/jekyll.git"
gem "minimal-mistakes-jekyll", :git => "https://github.com/mmistakes/minimal-mistakes.git", :branch => "feature/theme-gem"
group :jekyll_plugins do
# gem "jekyll-archives"
gem "jekyll-paginate"
gem "jekyll-sitemap"
gem "jekyll-gist"
gem "jekyll-feed"
gem "jemoji"
end
Step 3: Run Bundler
Run bundle install
(or bundle update
if you're updating an existing repo) to install the pre-release gems.
Step 4: Install the Theme
Add theme: "minimal-mistakes-jekyll"
to your _config.yml
file.
If you're migrating from an existing Minimal Mistakes site you shouldn't have to change anything else after this. If it's a new site consult then docs to [properly config]({{ "/docs/configuration/" | relative_url }}).
Please Note: Paths for image headers, overlays, teasers, [galleries]({{ "/docs/helpers/#gallery" | relative_url }}), and [feature rows]({{ "/docs/helpers/#feature-row" | relative_url }}) have changed and now require a full path. Instead of just image: filename.jpg
you'll need to use the full path eg: image: assets/images/filename.jpg
. The preferred location is now assets/images
but can be placed elsewhere or external hosted. This applies for image references in _config.yml
and author.yml
.
{: .notice--danger}
Step 5: jekyll new
Tweaks
If this is a new site be sure to add the following files to _data/
and customize as you see fit. There is currently no way of bundling them in with the theme, so be sure to consult the docs on how to properly use both.
_data/ui-text.yml
- UI text [documentation]({{ "/docs/ui-text/" | relative_url }})_data/navigation.yml
- navigation [documentation]({{ "/docs/navigation/" | relative_url }})
You'll also need to:
- Replace
<site root>/index.html
with a modified Minimal Mistakesindex.html
. - Change
layout: post
in_posts/0000-00-00-welcome-to-jekyll.markdown
tolayout: single
. - Remove
about.md
, or at the very least changelayout: page
tolayout: single
and remove references toicon-github.html
(or copy to your_includes
if using).
That's it! If all goes well running bundle exec jekyll serve
should spin-up your site. If you encounter any bumps please file an issue on GitHub and make sure to indicate you're testing the pre-release Ruby gem version.
File an issue{: .btn .btn--info .btn--large}
Thanks!