How to Migrate from WordPress to GitHub Pages Easily

Moving your blog from WordPress to GitHub Pages may sound complicated at first, but it’s actually simpler than most people think. Many creators are now switching to static site platforms like GitHub Pages because they want faster load times, lower costs, and complete control over their content. If you’re tired of constant plugin updates or server issues on WordPress, this guide will walk you through a smooth migration process to GitHub Pages using Jekyll — without losing your valuable posts, images, or SEO.

Why Migrate to GitHub Pages

WordPress is powerful, but it can become heavy over time — especially for personal or small blogs. Themes and plugins often slow down performance, while hosting costs continue to rise. GitHub Pages, on the other hand, offers a completely free, fast, and secure hosting environment for static sites. It’s perfect for bloggers who want simplicity without compromising professionalism.

When you migrate to GitHub Pages, you eliminate the need for:

• Database management (since Jekyll converts everything to static HTML)
• Plugin and theme updates
• Server or downtime issues

In return, you get faster loading speeds, better security, and total version control of your content — all backed by GitHub’s global CDN.

Exporting Your WordPress Content

The first step is to export your entire WordPress site. You can do this directly from the WordPress dashboard. Go to Tools → Export and select “All Content.” This will generate an XML file containing all your posts, pages, categories, tags, and metadata.

Download the XML file to your computer. This file will be the foundation for converting your WordPress posts into Jekyll-friendly Markdown files later.

WordPress → Tools → Export → All Content → Download Export File

It’s also a good idea to back up your wp-content/uploads folder so that you can migrate your images later.

Converting WordPress XML to Jekyll Format

Next, you’ll need to convert your WordPress XML export into Markdown files that Jekyll can understand. The easiest way is to use a conversion tool such as WordPress to Jekyll Exporter plugin or the command-line tool jekyll-import.

To use jekyll-import, install it via RubyGems:

gem install jekyll-import
ruby -rubygems -e 'require "jekyll-import";
    JekyllImport::Importers::WordPressDotCom.run({
      "source" => "wordpress.xml",
      "no_fetch_images" => false
    })'

This command will convert all your posts into Markdown files inside a _posts folder, automatically adding YAML front matter for each file.

Alternatively, if you want a simpler approach, use the official Jekyll Exporter plugin directly from your WordPress admin panel. It generates a zip file that already contains Jekyll-formatted posts and assets, ready for upload.

Setting Up Your Jekyll Site on GitHub Pages

Now that your content is ready, create a new repository on GitHub. If this is your personal blog, name it username.github.io. If it’s a project site, you can use any name. Clone the repository locally using Git:

git clone https://github.com/username/username.github.io
cd username.github.io

Then, initialize a new Jekyll site:

jekyll new .

Replace the default _posts folder with your converted content and copy your uploaded images into the assets directory. Commit and push your changes:

git add .
git commit -m "Initial Jekyll migration from WordPress"
git push origin main

Organizing Images and Assets

One common issue after migration is broken images. To prevent this, check all paths in your Markdown files. WordPress often stores images in directories like /wp-content/uploads/2024/01/. You’ll need to update these URLs to match your new structure in GitHub Pages.

Store all images inside /assets/images/ and use relative paths in your Markdown content, like:

![Alt text](/assets/images/photo.jpg)

This ensures your images load correctly whether viewed locally or online.

Preserving SEO URLs and Redirects

Maintaining your existing SEO rankings is crucial when migrating. To do this, you can preserve your old WordPress URLs or set up redirects. Add permalink structures to your _config.yml to match your old URLs:

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

If some URLs change, create a redirect_from entry in each page’s front matter using the Jekyll Redirect From plugin:

redirect_from:
  - /old-post-url/

This ensures users (and Google) who visit old links are automatically redirected to the new URLs.

Customizing Your Theme and Layout

Once your content is in place, it’s time to make your blog look great. You can choose from thousands of free Jekyll themes available online. Most themes are designed to work seamlessly with GitHub Pages.

To install a theme, simply edit your _config.yml file:

theme: minima

Or manually copy theme files into your repository for more control. Customize your _layouts and _includes folders to adjust your design, header, and footer. Because Jekyll uses the Liquid templating language, you can easily add dynamic elements like post loops, navigation menus, and SEO metadata.

Testing and Deploying Your Site

Before going live, test your site locally. Run the following command:

bundle exec jekyll serve

Visit http://localhost:4000 to preview your site. Check for missing links, broken images, and layout issues. Once you’re satisfied, commit and push again — GitHub Pages will automatically build and deploy your site.

After deployment, verify your site at https://username.github.io or your custom domain if configured.

Final Checklist for a Successful Migration

By following this process, you’ll have a clean, lightweight, and fast-loading blog hosted for free on GitHub Pages. The transition might take a day or two, but once complete, you’ll never have to worry about hosting fees or maintenance updates again. With full control over your content and code, GitHub Pages lets you focus on what truly matters — writing and sharing your ideas.