11 KiB
title | permalink | excerpt | last_modified_at | redirect_from | toc | |
---|---|---|---|---|---|---|
Quick-Start Guide | /docs/quick-start-guide/ | How to quickly install and setup Minimal Mistakes for use with GitHub Pages. | 2018-11-25T22:21:33-05:00 |
|
true |
Minimal Mistakes has been developed as a Gem-based theme for easier use, and 100% compatible with GitHub Pages when used as a remote theme.
If you enjoy this theme, please consider supporting me for developing and maintaining it.
Installing the theme
If you're running Jekyll v3.5+ and self-hosting you can quickly install the theme as a Ruby gem.
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 want them littering up your repo.
{: .notice--info}
Note: The theme uses the jekyll-include-cache plugin which will need to be installed in your Gemfile
and added to the plugins
array of _config.yml
. Otherwise you'll throw Unknown tag 'include_cached'
errors at build.
{: .notice--warning}
Gem-based method
With Gem-based themes, directories such as the assets
, _layouts
, _includes
, and _sass
are stored in the theme’s gem, hidden from your immediate view. This allows for easier installation and updating as you don't have to manage any of the theme files.
To install as a Gem-based theme:
-
Add the following to your
Gemfile
:gem "minimal-mistakes-jekyll"
-
Fetch and update bundled gems by running the following Bundler command:
bundle
-
Set the
theme
in your project's Jekyll_config.yml
file:theme: minimal-mistakes-jekyll
To update the theme run bundle update
.
Remote theme method
Remote themes are similar to Gem-based themes, but do not require Gemfile
changes or whitelisting making them ideal for sites hosted with GitHub Pages.
To install as a remote theme:
-
Create/replace the contents of your
Gemfile
with the following:source "https://rubygems.org" gem "github-pages", group: :jekyll_plugins
-
Add
jekyll-include-cache
to theplugins
array of your_config.yml
. -
Fetch and update bundled gems by running the following Bundler command:
bundle
-
Add
remote_theme: "mmistakes/minimal-mistakes@4.14.0"
to your_config.yml
file. Remove any othertheme:
orremote_theme:
entry.
You may also optionally specify a branch, tag, or commit to use by appending an @ and the Git ref (e.g., mmistakes/minimal-mistakes@4.9.0
or mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d
). This is useful when rolling back to older versions of the theme. If you don't specify a Git ref, the latest on master
will be used.
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.
![creating a new branch on GitHub](/N-archive/hacks-guide-minimal-mistakes-theme/media/commit/b689af7eea1cc1761b2be7bf1e1d2afef94f434b/docs/_docs/%7B%7B%20%27/assets/images/mm-gh-pages.gif%27%20%7C%20relative_url%20%7D%7D)
You can also install the theme by copying all of the theme files1 into your project.
To do so fork the Minimal Mistakes theme, then rename the repo to USERNAME.github.io --- replacing USERNAME with your GitHub username.
![fork Minimal Mistakes](/N-archive/hacks-guide-minimal-mistakes-theme/media/commit/b689af7eea1cc1761b2be7bf1e1d2afef94f434b/docs/_docs/%7B%7B%20%27/assets/images/mm-theme-fork-repo.png%27%20%7C%20relative_url%20%7D%7D)
GitHub Pages Alternatives: Looking to host your site for free and install/update the theme painlessly? Netflify, GitLab Pages, and Continuous Integration (CI) services 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 above. {: .notice--info}
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
Note: If forking the theme be sure to update Gemfile
as well. The one found at the root of the project is for building the theme's Ruby gem and is missing dependencies. To properly setup a Gemfile
with the theme, consult the "Install Dependencies" section.
{: .notice--warning}
Setup Your Site
Depending on the path you took installing Minimal Mistakes you'll setup things a little differently.
ProTip: The source code and content files for this site can be found in the /docs
folder if you want to copy or learn from them.
{: .notice--info}
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/" | relative_url }}) section.
From v4.5.0
onwards, Minimal Mistakes theme-gem comes bundled with the necessary data files and will automatically use them via the jekyll-data
plugin. So you no longer need to maintain a copy of these data files at your project directory.
However like all other bundled files, you'll need to create and edit these data files to customize them. The bundled data files are:
_data/ui-text.yml
- UI text [documentation]({{ "/docs/ui-text/" | relative_url }})_data/navigation.yml
- navigation [documentation]({{ "/docs/navigation/" | relative_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
. Then:
- Replace
<site root>/index.md
with a modified Minimal Mistakesindex.html
. Be sure to enable pagination if using the [home
layout]({{ "/docs/layouts/#home-page" | relative_url }}) by adding the necessary lines to _config.yml. - 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 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 the following folders and any files within them:
├── _includes
├── _layouts
├── _sass
├── assets
| ├── css
| ├── fonts
| └── js
You won't need these anymore as they're bundled with the theme gem --- unless you intend to override them.
Note: When clearing out the assets
folder be sure to leave any files you've added and need. This includes images, CSS, or JavaScript that aren't already bundled in the theme.
{: .notice--warning}
From v4.5.0
onwards, you don't have to maintain a copy of the default data files viz. _data/ui-text.yml
and _data/navigation.yml
either.
The default files are read-in automatically via the jekyll-data
plugin.
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.5"
. You'll need the latest version of Jekyll2 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.5"
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" | 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 externally hosted. This applies to 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.