Jekyll Minima: the default theme, and the v3 branch that will break your site

What Minima solves, and for whom

Minima is Jekyll's default and first theme. The README states plainly that it is what you get when you run jekyll new, which tells you the intended audience: writers who want a working blog without assembling layouts, Sass partials and includes by hand. The theme was scaffolded by the jekyll new-theme command, so it ships every directory a Jekyll site needs. That is the whole pitch. It is not a design system and it does not try to be one. If your requirement is a personal blog, a project changelog or documentation with dated posts, the theme covers it out of the box. If your requirement is a marketing site with custom components, you will spend your time overriding it rather than using it, and the override hooks are deliberately narrow, as the Sass section below explains.

Layouts, includes and the two override hooks

The theme's structure is visible in the repository layout: _layouts, _includes, _sass and assets. Layouts cover base.html (the foundation), home.html (the landing page), page.html (documents with front matter that are not posts) and post.html. The README notes that from v3 the base layout is named base.html instead of default.html, specifically to stop new users assuming the old name carries special status. That rename is the migration trap. Anyone with a customized _layouts/default.html is told to rename it to _layouts/base.html, or to create a thin default.html that declares layout: base and emits {{ content }} for backwards compatibility when several layouts were customized.

The include files are where the theme's optional behaviour lives, and most of it is gated on the Jekyll environment. comments.html renders Disqus comments and google-analytics.html inserts Google Analytics, and the README says both are active only when the environment is production. social.html renders icons from the minima:social_links config data using Font Awesome Free webfonts loaded from a remote CDN, which means the social row depends on a third-party request at page load.

The Sass side has exactly two extension points, and they are not interchangeable. minima/custom-variables.scss lets you override variable defaults and mixins but cannot override styles. minima/custom-styles.scss lets you override styles but cannot override variables. initialize.scss imports them in that order, so a variable you set in the wrong file silently does nothing. That is a real design constraint, not a documentation gap: the import order is the mechanism.

Installing Minima and publishing a first post

The README's installation section is two steps. Add the gem to your Jekyll site's Gemfile, then run bundle.

# Gemfile
gem "minima"

After bundle finishes, the theme is available to Jekyll. To confirm which copy is on disk, the README points to bundle show minima, which prints the local path to your current theme version. Run it before you edit anything, because the README bundled inside the gem is the one that matches your version, not the one on the repository's default branch.

If you would rather not install the gem, the README gives a second route through the jekyll-remote-theme plugin, pinning a specific commit.

# _config.yml
remote_theme: "jekyll/minima@1e8a445"

The same pinning works from a Gemfile, with theme: minima set in _config.yml.

# Gemfile
gem "minima", github: "jekyll/minima", ref: "1e8a445"

For a first real use, note the home layout behaviour: from v2.2 the home layout injects everything in your index.md or index.html before the Posts heading, so you can put introductory content above the post list. The README recommends titling that section with a Heading2. The post list itself is optional from v2.2 and appears only when the site has valid posts or drafts and show_drafts is configured. The list heading defaults to Posts in an h2 tag and can be changed with a list_title variable in the document's front matter. If you want an explicit h1 on the landing page, define title in that document's front matter.

The master branch warning is the main limitation

The README opens with a warning box, and it is worth taking literally: the master branch is under active development towards a semver-major release with non-backwards-compatible changes. The theme's own guidance is to point at a particular git ref rather than HEAD, and to move to a newer ref gradually via a pull request after consulting the commit log and README. Pointing directly at the HEAD commit of master is described as risky and possibly breaking your site's render.

That warning has a practical consequence for anyone who copies the repository's README as their installation guide. It is not the README for the version you are running. The theme says so explicitly: information here may vary depending on the version you're using, and you should read the README.md bundled within the theme-gem or open the Git tag for your version. The v2.5.0 tag is given as an example. So the correct first move is bundle show minima, then read the README at that path.

There is a second, quieter limitation. The release history is uneven. v2.5.2 is dated 2024-09-06, v2.5.1 is dated 2019-08-16 and v2.5.0 is dated 2018-04-20. A theme whose stable tags are years apart, while its development branch carries breaking changes, is one where the upgrade path is a deliberate manual exercise rather than a routine version bump. The last push to the repository was on 2026-04-07.

When Minima is the wrong choice

Minima is the wrong tool when your site's structure is not post-centric. The home layout's post listing is optional and driven by the presence of valid posts or drafts, and the layouts are base, home, page and post. There is no layout for archives, categories or tag pages. If you need those, you are writing them yourself, and at that point the theme's value is mostly its Sass defaults.

It is also the wrong tool if you cannot tolerate a moving target. The master branch is explicitly described as carrying changes that may break your site, so a workflow that tracks HEAD and deploys automatically is working against the theme's own advice. And it is the wrong tool if you dislike the two-hook override model. Being unable to override styles from custom-variables.scss, or variables from custom-styles.scss, is a constraint you will hit the first time you try to restyle a component by setting a variable in the wrong file.

How Minima differs from writing your own Jekyll theme

The realistic alternative is not another theme, it is a bare Jekyll site with your own _layouts and _sass. The difference is where the defaults live. With Minima you inherit a base layout, a home layout that injects index content before the Posts heading, four include files tied to production-only behaviour, and a classic skin imported through initialize.scss. With your own theme you inherit nothing and decide the import order yourself, which is exactly the freedom Minima removes when it fixes the sequence custom-variables, _base, _layout, custom-styles.

A second alternative is forking Minima and pinning your fork. That keeps the structure but moves the upgrade decision to you entirely: you would merge from the theme's commit log when you choose to, which is the same gradual process the README recommends for pinned refs, just with more control and more maintenance.

Licence and the cost of staying current

Minima is MIT licensed, and the repository carries a LICENSE.txt. MIT is permissive, so redistributing a modified theme inside your own project is within the terms, but this is not legal advice and you should read LICENSE.txt and your own obligations rather than relying on a summary here.

The upgrade cost is the part worth budgeting. Because the master branch is heading for a semver-major release with non-backwards-compatible changes, and because the stable tags are dated 2018-04-20, 2019-08-16 and 2024-09-06, the safe pattern is the one the README describes: pin a ref, then update to a newer ref through a pull request after reading the commit log. If you have customized layouts, add the v3 rename to your checklist, since base.html replaced default.html and the README offers a compatibility shim for sites with several customized layouts. Users on the gem install should run bundle show minima whenever they are unsure which version's behaviour they are reading about.

Editorial conclusion

Adopt Minima if you want a Jekyll site running with zero-configuration and you are willing to name a git ref in your Gemfile or _config.yml; the theme's own warning about the master branch is the strongest argument for pinning something immutable rather than tracking HEAD. Skip it if you need a layout system the theme does not ship, or if you cannot accept that upgrading means reading the commit log and opening a pull request yourself. Before you commit, run bundle show minima to confirm which version is actually on disk, and check whether your customized layouts still reference default.html, because v3 renamed the base layout to base.html.

Frequently asked questions

Official sources

1. jekyll/minima on GitHub
2. License: MIT
3. Project website
4. README
5. Releases