How do you migrate an existing blog into Jekyll directory structure
Migrating an existing blog into Jekyll’s directory structure can feel overwhelming at first, especially if your site has been running for years on WordPress, Blogger, or another CMS. The good news is that Jekyll offers a clean, organized way to manage your content with static files. In this guide, we walk through how to successfully transfer your blog, organize it into Jekyll’s folders, and ensure everything works smoothly on GitHub Pages.
Steps to follow when migrating your blog into Jekyll
- Why consider moving to Jekyll
- Preparing your existing content
- Understanding the core directory structure
- Converting posts into Markdown
- Handling images and media files
- Managing categories and tags
- Redirecting old URLs
- Common challenges and how to solve them
- FAQs on migrating blogs to Jekyll
- Final checklist for a smooth migration
Why consider moving to Jekyll
Traditional blogging platforms like WordPress and Blogger are excellent for beginners, but they often come with heavy databases, plugins, and server-side dependencies. Over time, this can slow down your site and introduce security risks. Jekyll, on the other hand, generates a static website. This means your site is faster, easier to maintain, and safer from common attacks. Hosting on GitHub Pages is also free, which makes it appealing for bloggers looking to cut costs.
Preparing your existing content
Before you begin migration, it’s important to take inventory of your existing blog. Create a list of:
- Total number of posts and pages
- Categories and tags in use
- Media files (images, videos, documents)
- Special templates or widgets you rely on
Export your content from your old platform. For WordPress, use the export XML feature. For Blogger, use Google’s Takeout tool. Having your data organized will make the migration process smoother.
Understanding the core directory structure
Jekyll organizes content into a few key folders. Knowing them helps you map your existing blog:
| Folder | Purpose |
|---|---|
| _posts | Stores blog posts in Markdown format, named by date. |
| _layouts | Holds templates for pages and posts. |
| _includes | Reusable snippets like headers and footers. |
| _data | YAML, JSON, or CSV files with structured data. |
| assets | Images, stylesheets, and JavaScript files. |
This structure is different from a CMS, but it simplifies maintenance in the long run.
Converting posts into Markdown
Most traditional blogging platforms store posts in HTML or database entries. Jekyll uses Markdown, which is cleaner and easier to edit. Use conversion tools like exitwp or jekyll-import to automate the process. For small blogs, you can manually copy content and reformat it in Markdown.
---
title: "My First Migrated Post"
date: 2020-05-10
categories: [travel]
tags: [jekyll,migration,static]
---
Welcome to my first post on Jekyll. This was originally published on WordPress.
Notice how metadata (front matter) sits at the top of each post. This is how Jekyll understands titles, dates, categories, and tags.
Handling images and media files
Images often represent the trickiest part of a migration. If your old blog used absolute URLs pointing to your old domain, you’ll need to update them. Best practice is to move all images into an assets/images folder. Then, reference them in Markdown:
This ensures your media files remain organized and portable if you ever change hosting providers.
Managing categories and tags
In WordPress or Blogger, categories and tags are usually stored in a database. In Jekyll, they are simply listed in the front matter. To recreate category or tag pages, you can use _layouts and loops in Liquid. Many Jekyll themes include built-in support for categories and tags, so check your theme documentation before building from scratch.
Redirecting old URLs
SEO can take a hit if you don’t properly redirect your old URLs. If your WordPress blog had URLs like /2020/05/10/post-title/ but Jekyll now uses /posts/post-title/, you need redirects. GitHub Pages doesn’t support traditional .htaccess, but you can create a redirect_from entry in your post front matter using the jekyll-redirect-from plugin.
redirect_from:
- /2020/05/10/post-title/
This helps preserve SEO value and prevents broken links.
Common challenges and how to solve them
- Formatting issues: Some HTML doesn’t convert cleanly to Markdown. Manual adjustments may be needed.
- Lost widgets: Jekyll doesn’t use plugins the way WordPress does. Replace widgets with includes or third-party scripts.
- Theme limitations: Not every WordPress design element can be replicated in Jekyll. Focus on content and usability first.
FAQs on migrating blogs to Jekyll
Do I lose my comments?
Yes, unless you use an external system like Disqus or Giscus. Jekyll itself doesn’t have a comment database.
What if I have thousands of posts?
Use automated migration tools. Manual migration for large sites is impractical. Tools like jekyll-import can handle bulk conversion.
Can I keep my old theme?
No, themes from WordPress or Blogger cannot be imported directly. You can replicate the look by customizing a Jekyll theme or building your own.
Final checklist for a smooth migration
Before declaring your migration complete, run through this list:
- Verify all posts have valid front matter.
- Check that images load correctly from
/assets. - Ensure categories and tags display properly.
- Test redirects for old URLs.
- Deploy on GitHub Pages and confirm everything builds without errors.
Migrating a blog to Jekyll requires effort, but the long-term benefits are worth it. With faster load times, lower costs, and full control of your content, you’ll have a platform that scales gracefully with your writing journey. Start small, test thoroughly, and enjoy the simplicity of Jekyll’s directory structure.