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
This commit is contained in:
Michael Rose 2017-11-10 11:20:38 -05:00
parent 4172237709
commit 6d9db31ef0
2 changed files with 52 additions and 36 deletions

View file

@ -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/ [tags-archive]: https://mmistakes.github.io/minimal-mistakes/tags/
[year-archive]: https://mmistakes.github.io/minimal-mistakes/year-archive/ [year-archive]: https://mmistakes.github.io/minimal-mistakes/year-archive/
## Usage ## Installation
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/). 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.
**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/)". ### Ruby Gem Method
## Quick Start 1. Install the theme as a Ruby Gem by adding it to your `Gemfile` like so:
Add this line to your Jekyll site's `Gemfile`: ```ruby
gem "minimal-mistakes-jekyll"
```
```ruby 2. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command:
gem "minimal-mistakes-jekyll"
```
Add this line to your Jekyll site's `_config.yml` file: ```bash
bundle
```
```yaml 3. Set the `theme` in your project's Jekyll `_config.yml` file:
theme: minimal-mistakes-jekyll
```
Then run Bundler to install the theme gem and dependencies: ```yaml
theme: minimal-mistakes-jekyll
```bash ```
bundle install
```
To update the theme run `bundle update`. 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 ## Contributing

View file

@ -2,13 +2,13 @@
title: "Quick-Start Guide" title: "Quick-Start Guide"
permalink: /docs/quick-start-guide/ permalink: /docs/quick-start-guide/
excerpt: "How to quickly install and setup Minimal Mistakes for use with GitHub Pages." 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: redirect_from:
- /theme-setup/ - /theme-setup/
toc: true 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 ## Installing the Theme
@ -50,23 +50,15 @@ gem "github-pages", group: :jekyll_plugins
gem "jekyll-remote-theme" 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: plugins:
- jekyll-remote-theme - 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.
<figure>
<img src="{{ '/assets/images/mm-theme-fork-repo.png' | absolute_url }}" alt="fork Minimal Mistakes">
</figure>
**Note:** Your Jekyll site should be viewable immediately at <http://USERNAME.github.io>. If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details). **Note:** Your Jekyll site should be viewable immediately at <http://USERNAME.github.io>. If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details).
{: .notice--warning} {: .notice--warning}
@ -76,15 +68,13 @@ If you're hosting several Jekyll based sites under the same GitHub username you
<img src="{{ '/assets/images/mm-gh-pages.gif' | absolute_url }}" alt="creating a new branch on GitHub"> <img src="{{ '/assets/images/mm-gh-pages.gif' | absolute_url }}" alt="creating a new branch on GitHub">
</figure> </figure>
Replace the contents of `Gemfile` found in the root of your Jekyll site with the following: You can also install the theme by copying all of the theme files[^structure] into your project.
```ruby 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.
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins <figure>
``` <img src="{{ '/assets/images/mm-theme-fork-repo.png' | absolute_url }}" alt="fork Minimal Mistakes">
</figure>
Then run `bundle update` and verify that all gems install properly.
**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. **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} {: .notice--info}