What Makes a Good Jekyll Theme? (Checklist Before You Buy)

A Jekyll theme can look polished in a screenshot and be a nightmare to work with in practice. Bad themes have hard-coded values scattered across templates, SCSS that cannot be overridden without editing source files, and JavaScript that blocks rendering on every page load.

A good Jekyll theme does the opposite: it is designed to be used, extended, and maintained — not just previewed. Here is what to look for before you commit.

Clean, Readable Liquid Templates

Open the theme’s _layouts/ and _includes/ directories on GitHub and read a few files. Well-written Liquid templates are:

Modular — the layout is broken into includes (_includes/header.html, _includes/footer.html, _includes/head.html) rather than crammed into one monolithic default.html. This makes it possible to override a single component without copying the entire layout.

Commented where it matters — complex Liquid logic (conditional includes, data lookups, paginator handling) should have a brief comment explaining what it does. Templates without any comments are harder to customise correctly.

Free of hard-coded content — good themes use _config.yml variables for site name, author, social links, and colour settings. A theme with your branding written directly into templates requires manual find-and-replace to customise.

Consistent naming conventions — front matter fields should follow a pattern (title, description, image, author) rather than an idiosyncratic mix that requires reading every template to understand.

Well-Organised SCSS

SCSS structure reveals a lot about how seriously a theme was built. A good Jekyll theme organises styles using:

Variables for everything visual — colours, font sizes, spacing, border radii, and breakpoints should all be defined as SCSS variables or CSS custom properties at the top of the stylesheet. This means you can retheme the entire site by changing a handful of values.

Logical file structure — styles split into logical partials: _variables.scss, _base.scss, _typography.scss, _layout.scss, _components.scss. A single style.scss file with 3,000 lines of undifferentiated CSS is a red flag.

No !important overuse — !important is sometimes necessary, but a theme that uses it everywhere is fighting its own specificity and will be painful to customise.

Dark mode handled properly — if the theme supports dark mode, it should use CSS custom properties swapped via a [data-theme="dark"] attribute or prefers-color-scheme media query, not a separate stylesheet loaded with JavaScript.

Performance by Default

A static site has no excuse to be slow. Before buying or installing a theme, check what it loads:

Minimal JavaScript — a blog or portfolio theme should need almost no JavaScript. If a theme loads jQuery, multiple animation libraries, and a carousel script for a site that displays text and images, those are unnecessary dependencies you will carry forever.

Self-hosted or system fonts — themes that load Google Fonts make an external request on every page load. A well-optimised theme either uses system fonts (font-family: system-ui, sans-serif) or bundles the fonts locally with font-display: swap.

Optimised images in templates — check the image includes. Does the theme use loading="lazy" on below-the-fold images? Does it specify width and height attributes to prevent layout shift?

No render-blocking resources — CSS should be in the <head>, JavaScript should be deferred or at the end of <body>. Check the source of the demo — a <script> tag without defer or async in the <head> will block every page from rendering.

Run Lighthouse on the live demo. A good Jekyll theme should score above 90 on Performance with no effort on your part — the theme itself should not be the bottleneck.

SEO Ready Out of the Box

A well-built Jekyll theme handles SEO fundamentals automatically:

jekyll-seo-tag integration — the theme should include {% seo %} in _layouts/default.html or equivalent. This handles title tags, meta descriptions, Open Graph, Twitter cards, and canonical URLs with a single include.

Proper heading hierarchy — one <h1> per page (the post or page title), with <h2> through <h4> used for content structure. A theme that wraps the site name in an <h1> on every page is hurting your SEO on every post.

RSS feed — the theme should include a <link rel="alternate" type="application/rss+xml"> in the head, pointing to a feed generated by jekyll-feed.

Structured data support — better themes include JSON-LD structured data for articles, breadcrumbs, or site links. This is not required, but it is a sign of a theme built with search visibility in mind.

Clean URLs — the theme should not produce URLs with .html extensions or unnecessary parameters. Jekyll handles this with permalink: pretty in _config.yml — check that the theme’s config sets this or documents how to do it.

Accessibility That Is Not an Afterthought

Accessibility in a theme is not just about compliance — it is about code quality. Themes that are accessible are also better structured, more maintainable, and more usable for everyone.

Semantic HTML — content should use <article>, <nav>, <main>, <aside>, and <footer> appropriately. A theme built entirely with <div> elements is not just inaccessible — it is lazy.

Skip navigation link — a “Skip to content” link as the first focusable element lets keyboard users bypass the navigation on every page. It is one line of HTML and CSS. Themes without it have not thought about keyboard navigation.

ARIA labels on interactive elements — icon-only buttons (like a dark mode toggle or search icon) need aria-label attributes to be usable by screen readers.

Focus styles — pressing Tab through the live demo should show a visible focus ring on every interactive element. Themes that remove focus styles with outline: none fail basic keyboard accessibility.

Colour contrast — body text on its background should meet WCAG AA (4.5:1 ratio minimum). Check this with the browser’s accessibility panel or a contrast checker.

Active Maintenance and a Clear Update History

Even the best theme becomes a liability if it is abandoned. Signs of a well-maintained theme:

A changelog — a CHANGELOG.md or release notes on GitHub showing what changed in each version. This tells you the author thinks carefully about changes and communicates them clearly.

Regular releases — at least a few updates in the past year. Check the releases page on GitHub, not just the commit history.

Responsive issue handling — open the GitHub issues and look for how the author responds to bug reports. Are bugs acknowledged and fixed? Or are issues sitting unanswered for months?

A versioning scheme — themes that use semantic versioning (1.2.0, 1.2.1) signal that the author understands the difference between a breaking change and a patch.

Good Documentation

Documentation is a direct measure of how much the author cares about the people using their theme.

A well-documented Jekyll theme covers:

Quick start — how to get the theme running locally in five minutes
Configuration reference — every _config.yml option explained with example values
Front matter fields — what each layout accepts and what is required vs optional
Customisation guide — how to override layouts, styles, and includes without editing theme source files
Deployment notes — any hosting-specific configuration required
Upgrade guide — what to do when a new version is released

If the only documentation is a README with a screenshot and a “fork this repo” instruction, the author has not thought about the experience of people actually using the theme.

The Quality Checklist

Use this before buying or installing any Jekyll theme:

Code quality

Templates are modular (split into _includes/)
No hard-coded content — everything comes from _config.yml or front matter
SCSS uses variables for colours, fonts, and spacing
No excessive !important usage
Dark mode uses CSS custom properties, not a separate stylesheet

Performance

Lighthouse performance score above 90 on the live demo
No unnecessary JavaScript libraries
Fonts are self-hosted or use system fonts
Images use loading="lazy" and have width/height attributes
No render-blocking scripts in <head>

SEO

Includes jekyll-seo-tag
One <h1> per page
RSS feed linked in <head>
Clean URLs (no .html extensions)

Accessibility

Uses semantic HTML elements (<article>, <nav>, <main>)
Has a skip navigation link
Icon buttons have aria-label attributes
Focus styles are visible
Body text passes WCAG AA contrast (4.5:1)

Maintenance

Last commit within 12 months
Has a changelog or release notes
Issues are responded to within a reasonable time
Compatible with Jekyll 4.x

Documentation

Quick start guide works
Configuration options are documented
Front matter fields are documented
Customisation without editing source files is explained

A theme that scores well on all five areas — code, performance, SEO, accessibility, and maintenance — is genuinely worth using. Most themes will excel in one or two and be mediocre in others. The checklist helps you make that trade-off consciously rather than discovering it after you have built your site.

Ready to find a theme that meets this standard? Browse the JekyllHub theme directory — every theme is hand-reviewed for quality before listing.

jekyll themes jekyll theme quality best jekyll themes premium jekyll themes jekyll theme checklist

Written by

Leila Vasquez

Designer & front-end developer. Making the web beautiful, one theme at a time.

View all posts by Leila Vasquez