A Jekyll Theme That Gets Out of Your Way (But Still Has 11 Skins If You Want Them)

You've picked Jekyll for your site. Now you're staring at a default template that looks like it was built in 2011, and you're trying to decide whether to spend your weekend on CSS or on actually writing content. Minimal Mistakes is a two-column Jekyll theme that gives you a clean, working foundation—then lets you decide how much further to take it.

What It Does

Minimal Mistakes is a flexible two-column Jekyll theme designed for personal sites, blogs, and portfolios. The styling is intentionally minimalistic—the README says it plainly: it's meant to be enhanced and customized by you. You get a working layout out of the box, and the theme stays out of your way while you make it yours.

Under the hood, it's bundled as a "theme gem," which means installation and upgrades go through your Gemfile rather than copying files around. It's compatible with GitHub Pages, supports Jekyll's built-in Sass/SCSS preprocessor, and ships with several responsive layout options: single, archive index, search, splash, and paginated home page. There's one gotcha worth flagging up front—the theme depends on the jekyll-include-cache plugin. You'll need it in your Gemfile and kept in the plugins array of _config.yml, or you'll hit Unknown tag 'include_cached' errors at build time.

Why It's Cool

• The skins give you options without forcing a redesign. The README advertises nine different color variations (the skins table actually lists 11 in addition to the default). If you don't want to touch a stylesheet to get a different look, you don't have to.

• It handles the SEO plumbing for you. Twitter Cards and Open Graph data support are built in. That's the kind of thing you usually remember you need a week after launch.

• The optional features cover real use cases. Header images, custom sidebars, table of contents, galleries, related posts, breadcrumb links, navigation lists—these aren't gimmicks, they're the things personal sites and blogs actually end up needing. Each one is optional, so you're not carrying weight you didn't ask for.

• Commenting is genuinely flexible. Disqus, Facebook, Google+, Discourse, Staticman (static-based), utterances, and giscus are all supported. The inclusion of static-based options like utterances and giscus is a nice touch for anyone who doesn't want a third-party script tracking their readers.

• The localization list is unusually thorough. UI text ships in English, Arabic, Brazilian Portuguese, Bulgarian, Catalan, Chinese, Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Irish, Italian, Japanese, Kiswahili, Korean, Malayalam, Burmese, Nepali, Norwegian, Persian, Polish, Punjabi, Romanian, Russian, Slovak, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese. If you write for an international audience, that's a lot of ground covered before you write a line of translation yourself.

• Analytics support includes a GDPR-friendly option. Google Analytics is there, and so is Swetrix, which the README describes as GDPR-compliant. Having a privacy-conscious choice alongside the default is a small but telling detail.

How to Try It

The repository is at github.com/mmistakes/minimal-mistakes, and there's a live preview at mmistakes.github.io/minimal-mistakes if you want to see the layouts and skins in action before committing.

Because it's packaged as a theme gem, the general flow looks like this:

1. Add the theme to your Gemfile:

gem "minimal-mistakes-jekyll"

1. Add the include-cache plugin (this is required—don't skip it):

gem "jekyll-include-cache"

1. In your _config.yml, set the theme and make sure the plugin stays in the plugins array:

theme: minimal-mistakes-jekyll
plugins:
  - jekyll-include-cache

1. Run bundle install and bundle exec jekyll serve to build locally.

From there, you'll want to check the theme's documentation for configuring layouts, skins, navigation, and the optional features. The README links to dedicated docs pages for headers, sidebars, table of contents, galleries, and breadcrumb navigation, so you're not left guessing.

Final Thoughts

Minimal Mistakes isn't trying to be the flashiest theme in the Jekyll ecosystem—it's trying to be the one you don't have to fight. The theme-gem packaging makes upgrades painless, GitHub Pages compatibility removes a common deployment headache, and the feature list is broad without being bloated, since almost everything is opt-in. The one hard requirement (that include-cache plugin) is worth internalizing before you start, but it's a small price for a theme that's been thoughtfully put together. If you're building a personal site or blog on Jekyll and want a clean starting point with room to grow, this is a solid place to begin.

Follow @githubprojects for more developer tools and open source projects.