How to Change Your Jekyll Theme (Without Losing Content)

Changing a Jekyll theme is straightforward if you follow the right steps. The key is understanding what belongs to the theme and what belongs to your content — so you can swap one without touching the other.

Before You Start: Back Up Your Site

Always create a git commit (or branch) before changing themes:

git checkout -b backup-before-theme-change
git add .
git commit -m "Backup before switching theme"
git checkout main

This gives you a safe rollback point.

Step 1: Audit Your Current Content

Identify what will need to migrate:

ls _posts/        # Your blog posts — always portable
ls _pages/        # Static pages — usually portable
ls _data/         # Data files — check if theme-specific
ls _includes/     # Custom includes — may need rewriting
ls _layouts/      # Custom layouts — may need rewriting

Your _posts/ content is always safe — Jekyll’s post format is universal. The files most likely to break are custom layouts and includes that reference theme-specific variables.

Step 2: Note Your Front Matter Defaults

Check _config.yml for any theme-specific settings:

# These are Minimal Mistakes specific — won't work in other themes
defaults:
  - scope:
      path: ""
      type: posts
    values:
      layout: "single"        # Theme-specific layout name
      author_profile: true    # Theme-specific variable
      sidebar:
        nav: "docs"           # Theme-specific sidebar

Write down any settings like these — you will need to find the equivalent in your new theme.

Step 3: Choose Your New Theme

Browse all Jekyll themes and pick one that matches your content type:

Blog → Chirpy, Minimal Mistakes, Clean Blog
Portfolio → al-folio, Hydejack
Documentation → Just the Docs
Personal → Hyde, Lanyon, Huxpro

Check that the new theme supports the layouts your posts use.

Step 4: Install the New Theme

For gem-based themes

Update Gemfile:

# Remove old theme
# gem "minima"

# Add new theme
gem "jekyll-theme-chirpy"

Update _config.yml:

# Remove old theme
# theme: minima

# Add new theme
theme: jekyll-theme-chirpy

Run:

bundle update
bundle exec jekyll serve

For GitHub-hosted themes

# _config.yml
remote_theme: cotes2020/jekyll-theme-chirpy

Step 5: Fix Broken Layouts

After switching, some posts may show errors like Layout 'single' does not exist. This means your posts use a layout name from the old theme.

Update the layout: field in affected posts, or set a default in _config.yml:

defaults:
  - scope:
      path: ""
      type: posts
    values:
      layout: "post"   # Use the new theme's post layout name

Step 6: Migrate Custom Pages

Static pages in _pages/ may reference old theme layouts. Check each one and update the layout: front matter to match the new theme’s available layouts.

Step 7: Preserve Your SEO

When changing themes, protect your existing SEO signals:

Keep the same URLs. Your post URLs are controlled by permalink in _config.yml, not the theme. Make sure this doesn’t change:

permalink: /:year/:month/:day/:title/

Keep your meta descriptions. Make sure the new theme uses jekyll-seo-tag or equivalent to render your post description fields.

Keep your sitemap. Add jekyll-sitemap to your Gemfile if the new theme doesn’t include it:

gem "jekyll-sitemap"

Step 8: Rebuild and Review

bundle exec jekyll clean
bundle exec jekyll serve --livereload

Check:

Homepage renders correctly
All posts are accessible
Images load properly
Navigation works
Mobile layout looks correct

Common Issues When Changing Themes

Issue	Cause	Fix
Posts show wrong layout	Old layout name in front matter	Update `layout:` or set defaults in `_config.yml`
Images broken	Different asset path convention	Check `baseurl` and image paths
Styles look wrong	Old SCSS overrides conflict	Remove or update `assets/css/main.scss`
Navigation missing	Old `_data/navigation.yml` format	Check new theme’s navigation format

References

change jekyll theme switch jekyll theme jekyll migration tutorial