What Is a Jekyll Theme and How Do You Use One?

A Jekyll theme is a packaged set of layouts, includes, stylesheets, and sometimes plugins that controls how a Jekyll site looks and is structured. You use one by declaring it in _config.yml and letting Jekyll pull its files in at build time, then overriding individual files in your own project when you need changes. This applies to any Jekyll site, including project homepages such as the OpenBVE Project homepage, which is built on Jekyll and lists theme and themes among its site keywords.

What a theme actually controls

A theme is not a single file. It is a bundle of the parts that determine presentation and page structure:

• Layouts — the HTML wrappers that pages and posts are rendered into (for example a default page layout and a post layout).
• Includes — reusable fragments such as headers, footers, and navigation.
• Stylesheets and assets — the CSS, and often fonts or images, that style the output.
• Optionally, plugins and configuration defaults — some themes ship a gemspec and default settings.

Because layouts and includes live in the theme, swapping themes can change the structure of every page at once, not just its colors.

Theme vs. template vs. plugin

These three are often confused, so keep the boundaries clear:

A theme can contain templates, and a theme can depend on plugins, but a template alone is not a theme and a plugin alone does not restyle your site.

Installing a theme

There are two common routes.

Gem-based theme

Add the theme to your Gemfile:

gem "jekyll-theme-example"

Then run bundle install. Jekyll resolves the theme from the installed gem, so you do not copy its files into your project.

Remote theme

If the theme is hosted on a Git repository and you use the jekyll-remote-theme plugin, you can point at it instead of installing a gem:

plugins:
  - jekyll-remote-theme
remote_theme: owner/repo

This is useful when you cannot or do not want to publish or install a gem.

Configuring the theme

Declare the theme in _config.yml:

theme: jekyll-theme-example

For a remote theme, use remote_theme as shown above instead of theme. After changing _config.yml, restart the local server so the new setting is picked up. The expected result is that pages render using the theme's layouts without any layout files present in your own project.

Overriding theme files without editing the gem

Never edit files inside an installed gem — your changes are lost on update. Instead, recreate the file at the same path in your own project. Jekyll prefers your local copy over the theme's version.

For example, to change a theme's default layout, create _layouts/default.html in your project and edit that. The same applies to _includes/, _sass/, and assets/. Copy only the files you actually need to change.

When a theme does not apply

Common causes and what to check:

• Theme not declared or misspelled — confirm the exact name in _config.yml matches the gem or repository.
• Gem not installed or not in the bundle — run bundle install and check the Gemfile.
• Remote theme plugin missing — remote_theme requires jekyll-remote-theme in plugins.
• Server not restarted — configuration changes need a restart, not just a rebuild.
• Local file shadowing the theme — an old layout or include in your project may be overriding the theme unintentionally.
• Build errors from missing plugins — if the theme depends on plugins, they must be available in your build environment.

If the site builds but looks unstyled, check that the theme's stylesheet is being referenced and that asset paths are correct.