hacks-guide-minimal-mistakes-theme/docs/_docs/01-quick-start-guide.md

title	permalink	excerpt	modified	redirect_from
Quick-Start Guide	/docs/quick-start-guide/	How to quickly install and setup Minimal Mistakes for use with GitHub Pages.	2016-11-03T10:01:43-04:00	/theme-setup/

Minimal Mistakes has been developed as a Jekyll theme gem for easier use. It is also 100% compatible with GitHub Pages --- just with a more involved installation process.

{% include toc %}

Installing the Theme

If you're running Jekyll v3.3+ and self-hosting you can quickly install the theme as Ruby gem. If you're hosting with GitHub Pages you'll have to use the old "repo fork" method or directly copy all of the theme files¹ into your site.

ProTip: Be sure to remove /docs and /test if you forked Minimal Mistakes. These folders contain documentation and test pages for the theme and you probably don't littering up in your repo. {: .notice--info}

Ruby Gem Method

Add this line to your Jekyll site's Gemfile:

gem "minimal-mistakes-jekyll"

Add this line to your Jekyll site's _config.yml file:

theme: minimal-mistakes-jekyll

Then run Bundler to install the theme gem and dependencies:

bundle install

GitHub Pages Compatible Method

Fork the Minimal Mistakes theme, then rename the repo to USERNAME.github.io --- replacing USERNAME with your GitHub username.

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}

If you're hosting several Jekyll based sites under the same GitHub username you will have to use Project Pages instead of User Pages. Essentially you rename the repo to something other than USERNAME.github.io and create a gh-pages branch off of master. For more details on how to set things up check GitHub's documentation.

Replace the contents of Gemfile found in the root of your Jekyll site with the following:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

group :jekyll_plugins do
  gem "jekyll-paginate"
  gem "jekyll-sitemap"
  gem "jekyll-gist"
  gem "jekyll-feed"
  gem "jemoji"
end

Then run bundle update and verify that all gems install properly.

Remove the Unnecessary

If you forked or downloaded the minimal-mistakes-jekyll repo you can safely remove the following folders and files:

• .editorconfig
• .gitattributes
• .github
• /docs
• /test
• CHANGELOG.md
• minimal-mistakes-jekyll.gemspec
• README.md
• screenshot-layouts.png
• screenshot.png

Setup Your Site

Depending on the path you took installing Minimal Mistakes you'll setup things a little differently.

Starting Fresh

Starting with an empty folder and Gemfile you'll need to copy or re-create this default _config.yml file. For a full explanation of every setting be sure to read the [Configuration]({{ "/docs/configuration/" | absolute_url }}) section.

After taking care of Jekyll's configuration file, you'll need to create and edit the following data files.

• _data/ui-text.yml - UI text [documentation]({{ "/docs/ui-text/" | absolute_url }})
• _data/navigation.yml - navigation [documentation]({{ "/docs/navigation/" | absolute_url }})

Starting from jekyll new

Scaffolding out a site with the jekyll new command requires you to modify a few files that it creates.

Edit _config.yml and create _data/ui-text.yml and _data/navigation.yml same as above. Then:

• Replace <site root>/index.md with a modified Minimal Mistakes index.html. Be sure to enable pagination if using the [home layout]({{ "/docs/layouts/#home-page" | absolute_url }}) by adding the necessary lines to _config.yml.
• Change layout: post in _posts/0000-00-00-welcome-to-jekyll.markdown to layout: single.
• Remove about.md, or at the very least change layout: page to layout: single and remove references to icon-github.html (or copy to your _includes if using it).

Migrating to Gem Version

If you're migrating a site already using Minimal Mistakes and haven't customized any of the theme files things upgrading will be easier for you.

Start by removing _includes, _layouts, _sass, assets folders and all files within. You won't need these anymore as they're bundled with the theme gem.

If you customized any of these files leave them alone, and only remove the untouched ones. If done correctly your modified versions should override the versions bundled with the theme and be used by Jekyll instead.

Update Gemfile

Replace gem "github-pages or gem "jekyll" with gem "jekyll", "~> 3.3.0". You'll need the latest version of Jekyll² for Minimal Mistakes to work and load all of the theme's assets properly, this line forces Bundler to do that.

Add the Minimal Mistakes theme gem:

gem "minimal-mistakes-jekyll"

When finished your Gemfile should look something like this:

source "https://rubygems.org"

gem "jekyll", "~> 3.3.0"
gem "minimal-mistakes-jekyll"

Then run bundle update and add theme: minimal-mistakes-jekyll to your _config.yml.

v4 Breaking Change: Paths for image headers, overlays, teasers, [galleries]({{ "/docs/helpers/#gallery" | absolute_url }}), and [feature rows]({{ "/docs/helpers/#feature-row" | absolute_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 all applies for image references in _config.yml and author.yml as well. {: .notice--danger}

---

That's it! If all goes well running bundle exec jekyll serve should spin-up your site.

---

1. See [Structure page]({{ "/docs/structure/" | absolute_url }}) for a list of theme files and what they do. ↩︎

2. You could also run bundle update jekyll to update Jekyll. ↩︎