# Minimal Mistakes: a two-column Jekyll theme you configure, not write

> Minimal Mistakes is a Jekyll theme gem for personal sites, blogs and documentation, installed as a theme gem and configured in _config.yml. Its value is in the layouts and skins it ships; its cost is that jekyll-include-cache is a hard dependency.

**mmistakes/minimal-mistakes** — :triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.

- Repository: https://github.com/mmistakes/minimal-mistakes
- Website: https://mmistakes.github.io/minimal-mistakes/
- Stars: 13,581 · Forks: 27,179
- Language: HTML
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/mmistakes-minimal-mistakes

## What Minimal Mistakes solves, and who ends up using it

Writing a Jekyll site from an empty directory means writing every layout yourself: the post template, the archive index, the paginated home page, the search page, the splash page. Minimal Mistakes exists so that work is already done. It is a two-column Jekyll theme, distributed as a theme gem, and the README describes its styling as purposely minimalistic, to be enhanced and customized by the user. That framing matters: the theme is a starting structure, not a finished design.

The people who get the most out of it are Jekyll users who want a blog, a personal site, project documentation or a portfolio without authoring Liquid templates. The theme ships several responsive layout options, which the README lists as single, archive index, search, splash and paginated home page. It also carries commenting support through Disqus, Facebook, Discourse, Staticman, utterances and giscus, plus Google Analytics and Swetrix analytics support. Those integrations are the reason many people pick it over a bare Jekyll scaffold.

The README also states the theme is compatible with GitHub Pages. That single line shapes a large part of its audience, because GitHub Pages users are the ones most likely to need a theme that works inside a hosted build they do not control.

## How the theme is structured: gem, skins, layouts, includes

The repository layout is a Jekyll site that doubles as the theme source. At the top level you find _layouts/, _includes/, _sass/, _data/, assets/, docs/ and _config.yml, alongside the gemspec and a Gemfile. That is the standard shape of a theme gem: the same directories that a site would use locally are packaged and shipped instead.

Skins are the visible customization axis. The README says the theme comes in 11 different skins in addition to the default one, and names air, contrast, dark, dirt, mint, sunrise, aqua, neon, plum, catppuccin_latte and catppuccin_mocha. Each skin is a color variation, and the README shows them as archive-page screenshots. Because the theme supports Jekyll's built-in Sass and SCSS preprocessor, changing a skin is a configuration change rather than a rewrite of the stylesheets.

The layout set is the other half of the mechanism. The README lists header images, custom sidebars, table of contents, galleries, related posts, breadcrumb links and navigation lists as optional features. Optional is the operative word: these are activated per page or per site through front matter and configuration, so a site that does not need a table of contents never renders one. The theme also handles Twitter Cards and Open Graph data for search engines and social previews, which the README presents as an SEO feature rather than something you wire up yourself.

One structural detail is easy to miss. The README warns that the theme uses the jekyll-include-cache plugin, that it must be installed in your Gemfile, and that it must be retained in the plugins array of _config.yml. Otherwise, the README says, you will encounter Unknown tag 'include_cached' errors at build. This is not an optional performance tweak. It is a build-time requirement baked into the theme's includes.

## Installing the theme gem and getting a first page rendered

The README states the theme is bundled as a theme gem for easier installation and upgrading, and it names jekyll-include-cache as a plugin that must be installed in your Gemfile and kept in the plugins array of _config.yml. The README does not print a full install walkthrough, and it does not show the Gemfile contents. The only literal key it gives for configuration is the plugins array, which appears in its warning about the include_cached error.

That warning is the whole of the setup guidance worth quoting. The plugins array in _config.yml is where jekyll-include-cache has to stay, and the README says removing it produces Unknown tag 'include_cached' errors at build.

```yaml
plugins:
  - jekyll-include-cache
```

Beyond that array, the README does not document the remaining install steps, so treat the theme gem's own README and the repository's Gemfile as the places to look rather than expecting a command sequence here. What you can check without guessing is the outcome: after the theme and plugin are in place, a post should render in the two-column layout. If instead you get an include_cached error, the plugins array is the first place to look.

## The include-cache dependency is the failure mode to plan for

The clearest limitation in the README is also the one most likely to bite during a migration. jekyll-include-cache is not bundled with the theme as a hidden internal detail; it has to be present in the Gemfile and listed in the plugins array. Any setup that strips the plugins array, or that runs in an environment where the plugin cannot be installed, breaks the build with Unknown tag 'include_cached'.

That matters most on hosted build systems. A platform that builds Jekyll for you may not let you add arbitrary gems, and the README's compatibility claim for GitHub Pages does not by itself guarantee that every plugin path is available there. The README does not document a fallback for environments where the plugin cannot be added, and it does not describe a build mode that avoids the cached includes. If your host refuses the plugin, the theme is the wrong tool for that host.

The second boundary is the theme's own design premise. The README calls the styling purposely minimalistic and expects the user to enhance and customize it. Anyone who wants a finished visual identity out of the box will spend the customization budget anyway. And the theme is Jekyll-specific: the repository is a Jekyll theme gem with Liquid includes and a Sass pipeline, so it does nothing for a Hugo, Eleventy or Next.js site. Choosing it is a commitment to Jekyll's build model.

## Minimal Mistakes compared with a plain Jekyll scaffold

The honest alternative is not another theme; it is Jekyll's own default scaffold, or a minimal theme you write yourself. The difference in approach is where the work sits. A plain Jekyll site gives you a post layout and little else. You then write the archive index, the paginated home page, the search page and the splash layout, and you decide how comments and analytics are injected into the templates.

Minimal Mistakes inverts that. Those layouts already exist in _layouts/, the color variations already exist as skins, and the third-party integrations are already wired into the theme's includes. Your work shifts from authoring Liquid to configuring _config.yml and front matter. The trade is control for speed: you inherit the theme's markup and its include structure, including the jekyll-include-cache dependency that comes with it.

A second real alternative is a hosted theme that is not a gem at all, where you copy files into your repository and edit them directly. That approach has no plugin requirement and no gem version to track, but it also has no upgrade path: upstream changes have to be merged by hand. The theme-gem model that Minimal Mistakes uses exists specifically so upgrades are a version bump rather than a manual diff, which is the README's stated reason for bundling it that way.

## Maintenance, upgrades and what the MIT licence leaves to you

The repository is not archived, and the last push was on 2026-08-11, which is the same date as the 4.28.1 release. Before that, 4.28.0 landed on 2026-03-11 and 4.27.3 on 2025-07-29. The release cadence visible in that list is a few releases a year rather than a constant stream, which is normal for a theme and also means you should not expect rapid responses to layout requests.

Upgrade cost depends on how far you have diverged. Because the theme is consumed as a gem, a version bump in the Gemfile is the upgrade mechanism, and the CHANGELOG is where the README points readers for what changed. The expense is in local overrides: any file you copied out of the theme into your own _layouts/ or _sass/ directories will not move with the gem, so those overrides need to be reconciled against the changelog by hand. The theme's own repository layout, with _layouts/, _includes/ and _sass/ at the top level, is a good map of which directories are likely to conflict.

The licence is MIT, per the repository's LICENSE file and the gemspec. MIT is permissive, so redistribution and modification are allowed, but the licence text and copyright notice need to be preserved with the code. That is a general property of MIT, not legal advice about your situation. If you fork the theme and ship it, the notice stays with it.

## Conclusion

Adopt Minimal Mistakes if you already build with Jekyll and want layouts, skins and commenting wired up without writing Liquid from scratch. Do not adopt it if you want a non-Jekyll static site generator, or if you cannot add jekyll-include-cache to your Gemfile and plugins array, since the build fails without it. Before committing, verify the plugins array in _config.yml, confirm your chosen skin exists in _sass/minimal-mistakes/skins, and check that your target host accepts the theme gem workflow.

## FAQ

### Is GitHub Pages Jekyll?

The Minimal Mistakes README states the theme is compatible with GitHub Pages, which is the connection the project documents. The README does not describe how GitHub Pages itself builds sites, so anything beyond that compatibility claim is outside what this material covers.

### How do I add a Jekyll theme like Minimal Mistakes?

Minimal Mistakes is bundled as a theme gem, and the README requires jekyll-include-cache to be installed in your Gemfile and retained in the plugins array of _config.yml. Removing it from that array produces Unknown tag 'include_cached' errors at build.

### What are some good themes for GitHub Pages?

The README states Minimal Mistakes is compatible with GitHub Pages and is a two-column Jekyll theme for personal sites, blogs, documentation and portfolios. It ships several responsive layouts, 11 skins in addition to the default, and commenting support through Disqus, Staticman, utterances and giscus, among others.

## Sources

- [Official documentation](https://mmistakes.github.io/minimal-mistakes/)
- [Official README](https://github.com/mmistakes/minimal-mistakes#readme)
- [Project repository](https://github.com/mmistakes/minimal-mistakes)
- [Release notes](https://github.com/mmistakes/minimal-mistakes/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mmistakes-minimal-mistakes