10 Things to Check Before Installing a Jekyll Theme

Installing a Jekyll theme takes minutes. Undoing a bad choice takes hours. Before you run bundle install, it is worth spending ten minutes checking these ten things — they will tell you whether a theme is genuinely well built or just good-looking in a screenshot.

1. Responsive Design — Actually Test It

Every theme claims to be responsive. Most are, to some degree. But “responsive” ranges from “barely not broken on mobile” to “carefully designed for every breakpoint.”

Open the live demo and resize your browser window from wide to narrow. Watch specifically for:

Navigation — does the hamburger menu work smoothly, or is it an afterthought?
Typography — does text remain readable at small sizes, or does it shrink too small?
Images — do they scale properly, or do they overflow their containers?
Tables and code blocks — do they scroll horizontally, or do they break the layout?

Also use your browser’s DevTools to simulate a real mobile device. Desktop responsive simulation and actual mobile rendering are not the same.

2. GitHub Pages Compatibility

If you want to host on GitHub Pages for free, this is a hard constraint. GitHub Pages runs Jekyll in safe mode — only a specific list of plugins are allowed.

Check the theme’s _config.yml and Gemfile for plugins. If you see anything beyond this standard set, it will not build on GitHub Pages without a CI/CD workaround:

plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-paginate
  - jekyll-relative-links

Plugins like jekyll-assets, jekyll-webp, or custom generators will fail. If the theme uses them but you want GitHub Pages, you will need GitHub Actions to build and deploy — which is doable but adds complexity.

3. Last Commit Date

Check the GitHub repository. When was the last commit?

Under 6 months — actively maintained
6–18 months — likely fine, minor risk
Over 18 months — proceed carefully, check open issues
Over 3 years — high risk of incompatibility with Jekyll 4.x

An abandoned theme will not keep up with Jekyll updates, browser changes, or security fixes. At some point it will stop building correctly, and you will have no upstream to pull fixes from.

4. Jekyll Version Compatibility

Related to maintenance — check which version of Jekyll the theme targets. Open the Gemfile or _config.yml and look for a Jekyll version constraint:

gem "jekyll", "~> 4.3"

If the theme was built for Jekyll 2.x or early 3.x, it may use deprecated Liquid syntax, old plugin APIs, or layout structures that have changed. A quick check is to look at the README — does it mention Jekyll 4? Does it use {{ content }} in _layouts/default.html? Old themes sometimes use the pre-3.0 layout syntax.

5. Documentation Quality

Read the README before installing anything. A well-documented theme should cover:

Installation — gem-based or direct file copy, Gemfile requirements
Configuration — what goes in _config.yml, with example values
Front matter — what fields each layout accepts
Customisation — how to override styles or layouts without editing theme files
Deployment — any hosting-specific notes

If the README is a screenshot and a link to the demo, expect to spend significant time reverse-engineering how the theme works. That is fine if you enjoy that kind of exploration — but it is a real time cost.

6. Performance — Check the Real Numbers

Open the live demo in Chrome and run Lighthouse (DevTools → Lighthouse tab). Check the Performance score and specifically look at:

First Contentful Paint — should be under 1.5s
Largest Contentful Paint — should be under 2.5s
Total Blocking Time — should be under 300ms
Page weight — open the Network tab and check total transfer size

A Jekyll theme has no excuse to be slow. It generates static HTML — if a theme is loading multiple large JavaScript bundles, external font files, or unoptimised images, those are design choices you will carry into production.

7. Accessibility Basics

You do not need to run a full WCAG audit, but checking a few basics takes two minutes and tells you a lot about the quality of the code:

Keyboard navigation — press Tab through the live demo. Can you reach every link and button? Does the focus ring appear?

Colour contrast — use your browser’s accessibility panel or a tool like WebAIM’s contrast checker on the body text and background. WCAG AA requires a 4.5:1 ratio for normal text.

Image alt text — look at the theme’s image includes. Do they use alt="" or alt=""? Blank alt text is sometimes intentional for decorative images, but it should not be a blanket default.

Heading structure — is there one <h1> per page? Do headings follow a logical hierarchy without skipping levels?

Themes that fail basic accessibility checks reveal poor attention to detail in the underlying code.

8. SEO Structure

A Jekyll theme should output clean HTML that search engines can parse easily. Check:

jekyll-seo-tag support — does the theme include {% seo %} in the <head>? This plugin handles title tags, meta descriptions, Open Graph tags, and Twitter cards automatically.

Canonical URLs — does the theme output <link rel="canonical"> tags? This prevents duplicate content issues.

Structured heading hierarchy — as above, one <h1> per page, used for the post or page title.

RSS feed — does the theme include a link to an RSS/Atom feed? This is important for discoverability and feed aggregators.

Sitemap — does it support jekyll-sitemap for automatic sitemap generation?

9. Browser Support

Most modern Jekyll themes support current browsers without issue, but it is worth checking if your audience includes users on older browsers or specific platforms.

Open the live demo in Firefox, Safari, and Chrome — at minimum. Look for any rendering differences in fonts, layout, or interactive elements. Some themes use CSS features (like container queries or newer selectors) that have uneven support.

If you have analytics from a previous site, check what browsers your audience actually uses before deciding how much weight to give this.

10. Licence and Usage Rights

This one is easy to forget until it matters. Check the theme’s licence before using it commercially:

MIT — most permissive, use for anything including commercial projects
GPL — copyleft, your site’s code may need to be open source
CC BY — requires attribution, fine for most use cases

Premium themes typically come with a commercial licence for a set number of sites. Read it carefully if you are building for a client or plan to run ads or sell products on the site.

The Quick Checklist

Run through these before committing:

A theme that passes all ten is genuinely worth installing. Most themes will pass most of them — the checklist helps you spot the two or three that matter for your specific situation.

Next step: How to Install a Jekyll Theme.

jekyll themes jekyll theme checklist install jekyll theme jekyll theme quality

Written by

Marcus Webb

Documentation nerd. I believe great docs change the world. Author of DevDocs Pro.

View all posts by Marcus Webb