Skip to content
Get packs

Guide · Open source

How to use Minimal Mistakes: Jekyll theme setup and customization

Updated · written with AI from the project's own documentation and checked against our catalogue data

Minimal Mistakes is a free, MIT-licensed Jekyll theme: a set of templates and styles that turns plain text files into a two-column website for a personal site, blog, project documentation, or portfolio. This guide explains what you need before you start, how to get the theme, the one plugin you must not remove, and where to customize it. By the end you will know how to get a working Jekyll site with the theme and where its main options live.

Minimal Mistakesmmistakes/minimal-mistakes · ★ 13.6k · MIT

Quick start

  1. 1Check your Jekyll version. Confirm you have Jekyll 3.7 or newer, as listed in the README badge.
  2. 2Clone the repository. Run git clone https://github.com/mmistakes/minimal-mistakes.git to download the theme.
  3. 3Add the required plugin. Install jekyll-include-cache in your Gemfile and keep it in the plugins array of _config.yml.
  4. 4Pick a skin. Choose one of the 11 skins or the default, and set it in your configuration.
  5. 5Add your content. Write posts or pages as plain text files, using the layouts that suit your site.
  6. 6Customize with Sass/SCSS. Override styles using Jekyll's built-in Sass/SCSS support to match your design.
  7. 7Build and check for errors. Run a build and confirm there are no Unknown tag errors before publishing.

What you need before you start

Minimal Mistakes is built on Jekyll, so you need a working Jekyll setup. The README badge lists Jekyll 3.7 or newer as the requirement. The theme is also a good fit if you plan to publish on GitHub Pages, which the README lists as compatible.

The README says setup and customization assume a Ruby-based toolchain. If you do not want to work with Jekyll or Ruby tooling, this theme is not a good match, because it is a theme to customize rather than a finished site builder.

  • Jekyll 3.7 or newer
  • Comfort with editing text files and configuration
  • Optional: a GitHub account if you publish on GitHub Pages

Get the theme from the repository

The README's install step is to clone the repository. Run the command below from the folder where you want the project to live.

Once cloned, the theme's files are in the repository and you can build your site from them. Check the README and the homepage documentation for the exact next steps for your setup.

git clone https://github.com/mmistakes/minimal-mistakes.git

Keep the jekyll-include-cache plugin configured

The theme uses the jekyll-include-cache plugin. The README says it must be installed in your Gemfile and must stay in the plugins array of _config.yml. If you leave it out, the build fails with an Unknown tag 'include_cached' error.

Treat this as the first thing to check when a build breaks after you edit configuration.

  • Add jekyll-include-cache to your Gemfile
  • Keep it in the plugins array in _config.yml
  • If you see Unknown tag 'include_cached', re-check both files

Choose a skin and layout

The README says the theme comes in 11 skins in addition to the default one. Skins are colour variations, including air, contrast, dark, dirt, mint, sunrise, aqua, neon, plum, catppuccin_latte and catppuccin_mocha.

Layouts include single, archive index, search, splash, and a paginated home page. Optional features include header images, custom sidebars, a table of contents, galleries, related posts, breadcrumb links and navigation lists.

  • Skins change colours, not structure
  • Header images, sidebars and table of contents are optional
  • Demo pages in the README show posts, categories and tags archives

Customize styling with Sass/SCSS

The theme supports Jekyll's built-in Sass/SCSS preprocessor. Because the default styling is kept deliberately simple, customization is the expected path rather than an exception.

Commenting and analytics are also optional. The README lists Disqus, Facebook comments, Discourse, Staticman, utterances and giscus for comments, plus Google Analytics and Swetrix for analytics. Enable only the ones you need.

  • Use Jekyll's Sass/SCSS support for style changes
  • Pick one comment system or none
  • Google Analytics and Swetrix (GDPR-compliant) are both listed

What people use it for

  • A personal portfolio with a splash or single-page layout
  • A blog with an archive index, categories and tags
  • Project documentation with search and navigation lists
  • A GitHub Pages site built from a Jekyll theme

Frequently asked questions

Is Minimal Mistakes free to use?

Yes. The README lists the licence as MIT. Check the LICENSE file in the repository for the full terms.

What version of Jekyll does Minimal Mistakes need?

The README badge lists Jekyll 3.7 or newer. Use a version at or above that before you install the theme.

Can I host Minimal Mistakes on GitHub Pages?

The README lists GitHub Pages as compatible, so it is a supported publishing target. Keep the jekyll-include-cache plugin configured as described in the README.

Why do I get an Unknown tag 'include_cached' error?

The theme needs the jekyll-include-cache plugin. Add it to your Gemfile and keep it in the plugins array of _config.yml, as the README instructs.

Does Minimal Mistakes work without knowing Ruby?

Not really. The README says setup and customization assume a Jekyll and Ruby-based toolchain, so you will need to be comfortable with it.

How does Minimal Mistakes compare to Academic Pages, Jekyll Now or Hugo PaperMod?

Academic Pages, Jekyll Now and Hugo PaperMod are comparable projects in the same space. This source does not compare them directly, so review each project's documentation to decide which fits your stack.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Minimal Mistakes suits people who want a customizable Jekyll theme for a personal site, blog, documentation or portfolio, especially on GitHub Pages. If you want a finished site with no code or Ruby tooling, pick a hosted builder or a different project instead.

Install options & downloads