Minimal Mistakes
A two-column Jekyll theme for personal sites, blogs, docs, and portfolios.
- Stars
- 13.6k
- Forks
- 27.1k
- Licence
- MIT
- Language
- HTML
- Last update
- 28 days ago
- Type
- Library
What it is
Minimal Mistakes is a Jekyll theme, a set of templates and styles that turns plain text files into a website. It has a two-column layout and is meant to be customized, so its styling is kept deliberately simple. People use it for personal sites, blogs, project documentation, and portfolios.
- Publish a personal portfolio with a splash or single-page layout
- Run a blog with an archive index, categories, and tags pages
- Document a project using navigation lists and a table of contents
- Add comments through services the README lists, such as utterances or giscus
- Add Google Analytics or Swetrix analytics to a site
Great for
- People who want a personal site or blog built with Jekyll
- Anyone publishing on GitHub Pages, which the README lists as compatible
- Developers who want to customize a theme with Jekyll's Sass/SCSS support
- Project documentation sites that need search and navigation options
Not ideal for
- People who do not want to work with Jekyll or Ruby-based tooling, since setup and customization assume that toolchain
- Users who need a site builder with no code or configuration, because the README describes a theme to be customized rather than a finished product
How to get it
- 1
See the README
You'll need: Jekyll 3.7 or newer (per the README badge)
Clone the repository
git clone https://github.com/mmistakes/minimal-mistakes.git - 2
Run it
- Clone the repository or add the theme gem to your Jekyll site's Gemfile
- Add the jekyll-include-cache plugin to your Gemfile and to the plugins array in _config.yml
- Set the theme in your site configuration
- Run Jekyll locally to preview the site in your browser
- Edit the sample posts and configuration to fit your own content
- 3
Get the most out of it
- Pick one of the bundled skins (the README lists several color variations) to change the look without custom CSS
- Use header images, custom sidebars, and galleries described in the documentation to build richer layouts
- Add a comment system such as utterances or giscus if you want reader discussion
- Use Jekyll's Sass/SCSS support to override the default styles
- Check the CHANGELOG when upgrading, since the theme is distributed as a gem
Downloads
Strengths
- Flexible two-column layout that is meant to be customized
- Compatible with GitHub Pages and distributed as a theme gem for easier installation and upgrades
- Released under the MIT license
Trade-offs
- Requires the jekyll-include-cache plugin in the Gemfile and in the plugins list of _config.yml, or the build fails with an 'Unknown tag' error
- Assumes familiarity with Jekyll; the README does not walk a beginner through a full setup
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| minimal-mistakes (this) | 13.6k | Library | intermediate | 28 days ago | People who want a personal site or blog built with Jekyll |
| hugo-PaperMod | 14k | Other | intermediate | 12 days ago | Bloggers who already use or want to use Hugo |
| al-folio | 16.3k | App | intermediate | 11 days ago | Academics and researchers who want a personal website with a clean, responsive layout |
| academicpages.github.io | 17.8k | Other | beginner | 4 days ago | Academics who want a personal homepage listing publications and talks |
| jekyll-theme-chirpy | 10.3k | Library | intermediate | 2 months ago | Developers who want a technical blog without designing a site from scratch |
| tabler | 42k | Library | beginner | 7 days ago | Developers building internal admin panels or dashboards quickly |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.