From 6d9db31ef0e71f809fad1d873a7d86d360beb7ca Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Fri, 10 Nov 2017 11:20:38 -0500 Subject: [PATCH] Update installation documentation Include new `jekyll-remote-theme` method for using Ruby gem version of the theme with GitHub Pages hosted sites. ref: https://github.com/mmistakes/minimal-mistakes/issues/1339 --- README.md | 60 +++++++++++++++++++++--------- docs/_docs/01-quick-start-guide.md | 28 +++++--------- 2 files changed, 52 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index fc64af2c4bbd..f8969edeff68 100644 --- a/README.md +++ b/README.md @@ -65,34 +65,60 @@ Additional sample posts are available under [posts archive][year-archive] on the [tags-archive]: https://mmistakes.github.io/minimal-mistakes/tags/ [year-archive]: https://mmistakes.github.io/minimal-mistakes/year-archive/ -## Usage - -For detailed instructions on how to configure, customize, add content, and more read the [theme's documentation](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/). +## Installation -**Note:** Gem version of the theme requires Jekyll v3.3+ and is not currently supported on [GitHub Pages](https://pages.github.com/). You can still use the theme with GitHub Pages, you'll just need to install using the old "[repo fork method](https://mmistakes.github.io/minimal-mistakes/docs/installation/)". +There are three ways to install the theme: as a Ruby gem (for self-hosted sites), as a Ruby gem + jekyll-remote-theme plugin (GitHub Pages hosted sites), or forking/directly copying all of the theme files into your project. -## Quick Start +### Ruby Gem Method -Add this line to your Jekyll site's `Gemfile`: +1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so: -```ruby -gem "minimal-mistakes-jekyll" -``` + ```ruby + gem "minimal-mistakes-jekyll" + ``` -Add this line to your Jekyll site's `_config.yml` file: +2. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command: -```yaml -theme: minimal-mistakes-jekyll -``` + ```bash + bundle + ``` -Then run Bundler to install the theme gem and dependencies: +3. Set the `theme` in your project's Jekyll `_config.yml` file: -```bash -bundle install -``` + ```yaml + theme: minimal-mistakes-jekyll + ``` To update the theme run `bundle update`. +## GitHub Pages Compatible Methods + +1. Create/replace the contents of your `Gemfile` with the following: + + ```ruby + source "https://rubygems.org" + + gem "github-pages", group: :jekyll_plugins + gem "jekyll-remote-theme" + ``` + +2. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command: + + ```bash + bundle + ``` + +3. Add `jekyll-remote-theme` to the `plugins` (previously gems) array in your `_config.yml` file: + + ```yaml + plugins: + - jekyll-remote-theme + ``` + +## Usage + +For detailed instructions on how to configure, customize, add/migrate content, and more read the [theme's documentation](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/). + --- ## Contributing diff --git a/docs/_docs/01-quick-start-guide.md b/docs/_docs/01-quick-start-guide.md index 4c5e24253def..6fb2228132ab 100644 --- a/docs/_docs/01-quick-start-guide.md +++ b/docs/_docs/01-quick-start-guide.md @@ -2,13 +2,13 @@ title: "Quick-Start Guide" permalink: /docs/quick-start-guide/ excerpt: "How to quickly install and setup Minimal Mistakes for use with GitHub Pages." -last_modified_at: 2017-11-07T20:48:04-05:00 +last_modified_at: 2017-11-08T09:30:30-05:00 redirect_from: - /theme-setup/ toc: true --- -Minimal Mistakes has been developed as a [Jekyll theme gem](http://jekyllrb.com/docs/themes/) for easier use. It is also 100% compatible with GitHub Pages --- just with a more involved installation process. +Minimal Mistakes has been developed as a [Jekyll theme gem](http://jekyllrb.com/docs/themes/) for easier use. It is also 100% compatible with GitHub Pages --- just with slightly different installation process. ## Installing the Theme @@ -50,23 +50,15 @@ gem "github-pages", group: :jekyll_plugins gem "jekyll-remote-theme" ``` -Then run `bundle update` and verify that all gems install properly. +Run `bundle update` and verify that all gems install properly. -Finally add `jekyll-remote-theme` to the `plugins` (previously gems) array in your `_config.yml` file like so: +Then add [`jekyll-remote-theme`](https://github.com/benbalter/jekyll-remote-theme) to the `plugins` (previously gems) array in your `_config.yml` file like so: ``` plugins: - jekyll-remote-theme ``` -You can also install the theme by forking or copying all of the theme files[^structure] into your site. - -To do so fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/fork), then rename the repo to **USERNAME.github.io** --- replacing **USERNAME** with your GitHub username. - -
- fork Minimal Mistakes -
- **Note:** Your Jekyll site should be viewable immediately at . If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details). {: .notice--warning} @@ -76,15 +68,13 @@ If you're hosting several Jekyll based sites under the same GitHub username you creating a new branch on GitHub -Replace the contents of `Gemfile` found in the root of your Jekyll site with the following: - -```ruby -source "https://rubygems.org" +You can also install the theme by copying all of the theme files[^structure] into your project. -gem "github-pages", group: :jekyll_plugins -``` +To do so fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/fork), then rename the repo to **USERNAME.github.io** --- replacing **USERNAME** with your GitHub username. -Then run `bundle update` and verify that all gems install properly. +
+ fork Minimal Mistakes +
**GitHub Pages Alternatives:** Looking to host your site for free and install/update the theme painlessly? [Netflify][netlify-jekyll], [GitLab Pages][gitlab-jekyll], and [Continuous Integration (CI) services][ci-jekyll] have you covered. In most cases all you need to do is connect your repository to them, create a simple configuration file, and install the theme following the [Ruby Gem Method](#ruby-gem-method) above. {: .notice--info}