hacks-guide-minimal-mistake.../_docs/03-installation.md

80 lines
4.3 KiB
Markdown
Raw Normal View History

2016-04-04 22:36:26 +02:00
---
title: "Installation"
permalink: /docs/installation/
excerpt:
sidebar:
2016-04-06 03:50:10 +02:00
title: "v3.0"
2016-04-04 22:36:26 +02:00
nav: docs
2016-04-13 23:10:01 +02:00
modified: 2016-04-13T15:54:02-04:00
2016-04-04 22:36:26 +02:00
---
{% include base_path %}
## Install the Theme
2016-04-05 22:55:13 +02:00
There are several ways to install the theme:
2016-04-04 22:36:26 +02:00
2016-04-14 04:38:28 +02:00
**1.** For a **new site**, fork the Minimal Mistakes repo on GitHub. If you plan on hosting your site with GitHub Pages follow the steps outlined in the [*Quick-Start Guide*]({{ base_path }}/docs/quick-start-guide/).
2016-04-04 22:36:26 +02:00
2016-04-05 22:55:13 +02:00
**2.** For an **existing site** you have some more work ahead of you. What I suggest is to fork and rename the theme's repo as before, then clone it locally by running `git clone https://github.com/USERNAME/REPONAME.git` --- replacing **USERNAME** and **REPONAME** with your own.
2016-04-04 22:36:26 +02:00
2016-04-05 03:16:25 +02:00
<figure>
2016-04-09 03:49:50 +02:00
<img src="{{ base_path }}/images/mm-github-copy-repo-url.jpg" alt="copy GitHub repo URL">
2016-04-05 22:55:13 +02:00
<figcaption>Tap the copy to clipboard button (outlined in red above) to grab your GitHub repo's path.</figcaption>
2016-04-05 03:16:25 +02:00
</figure>
2016-04-04 22:36:26 +02:00
2016-04-05 22:55:13 +02:00
**3.** And for those who don't want to mess with Git, you can download the theme as a ZIP file to work with locally.
2016-04-04 22:36:26 +02:00
2016-04-12 20:34:36 +02:00
[<i class="fa fa-download"></i> Download Minimal Mistakes Theme]({{ site.gh_repo }}/archive/master.zip){: .btn .btn--success}
2016-04-04 22:36:26 +02:00
2016-04-11 22:19:43 +02:00
**ProTip:** Be sure to [delete](https://github.com/blog/1377-create-and-delete-branches) the `gh-pages` branch if you forked Minimal Mistakes. This branch contains the documentation and demo site for the theme and you probably don't want that showing up in your repo.
{: .notice--info}
2016-04-05 22:55:13 +02:00
---
2016-04-04 22:36:26 +02:00
2016-04-14 04:38:28 +02:00
To move over any existing content you'll want to copy the contents of your `_posts` folder to the new site. Along with any pages, collections, data files, images, or other assets you may have.
2016-04-05 22:55:13 +02:00
Next you'll need to convert posts and pages to use the proper layouts and settings. In most cases you simply need to update `_config.yml` to your liking and set the correct `layout` in their YAML Front Matter.
[**Front Matter defaults**](https://jekyllrb.com/docs/configuration/#front-matter-defaults) are your friend and I encourage you to leverage them instead of setting a layout and other global options in each post/page's YAML Front Matter.
2016-04-14 04:38:28 +02:00
Posts can be configured to use the `single` layout --- with reading time, comments, social sharing links, and related posts enabled. Adding the following to `_config.yml` will set these defaults for all posts:
2016-04-05 22:55:13 +02:00
```yaml
defaults:
# _posts
- scope:
path: ""
type: posts
values:
layout: single
read_time: true
comments: true
share: true
related: true
```
2016-04-14 04:38:28 +02:00
**Post/Page Settings**: Be sure to read through the "Working with..." documentation to learn about all the options available to you. The theme has been designed to be flexible --- with numerous settings for each.
2016-04-05 22:55:13 +02:00
{: .notice--info}
2016-04-04 22:36:26 +02:00
## Install Dependencies
2016-04-14 04:38:28 +02:00
If this is your first time using Jekyll be sure to read through the [official documentation](https://jekyllrb.com/docs/home/) before jumping in. This guide assumes you have Ruby v2 installed and a basic understanding of how Jekyll works.
2016-04-04 22:36:26 +02:00
2016-04-14 04:38:28 +02:00
To keep your sanity and better manage dependencies I strongly urge you to [install Bundler](http://bundler.io/) with `gem install bundler` and use the included [`Gemfile`]({{ site.gh_repo }}/blob/master/Gemfile). The theme's Gemfile includes the `github-pages` gem to maintain a local Jekyll environment in sync with GitHub Pages.
2016-04-04 22:36:26 +02:00
2016-04-14 04:38:28 +02:00
If you're not planning on hosting with GitHub Pages and want to leverage features found in the latest version of Jekyll, replace `gem "github-pages"` with `gem "jekyll"` in your `Gemfile`. In either case run the following:
2016-04-04 22:36:26 +02:00
```bash
$ bundle install
```
2016-04-05 03:16:25 +02:00
<figure>
<img src="{{ base_path }}/images/mm-bundle-install.gif" alt="bundle install in Terminal window">
</figure>
2016-04-04 22:36:26 +02:00
2016-04-14 04:38:28 +02:00
Depending on what gems you already have installed you may have to run `bundle update` to clear up any dependency issues. Bundler is usually pretty good at letting you know what gems need updating or have issues installing, to further investigate.
2016-04-05 22:55:13 +02:00
2016-04-14 04:38:28 +02:00
When using Bundler to manage gems you'll want to run Jekyll using `bundle exec jekyll serve` and `bundle exec jekyll build`.
2016-04-05 22:55:13 +02:00
2016-04-14 04:38:28 +02:00
Doing so executes the gem versions specified in `Gemfile.lock`. Sure you can test your luck with a naked `jekyll serve`, but I wouldn't suggest it. A lot of Jekyll errors originate from outdated or conflicting gems fighting with each other. So do yourself a favor and just use Bundler.