How to Move from WordPress to Jekyll Using Mediumish Theme

Why Consider Moving from WordPress to Jekyll with Mediumish?

If you've used WordPress for years and are tired of constant updates, plugin vulnerabilities, and slow performance, you're not alone. Many developers and content creators are shifting to static site generators like Jekyll. But why the Mediumish theme specifically? And why host it on GitHub Pages?

In this case study, we’ll break down every part of the process and stack. You’ll learn the "why" and the "how" behind moving a live blog from WordPress to Jekyll using the popular Mediumish theme, hosted completely free on GitHub Pages.

What Is the Jekyll + Mediumish + GitHub Pages Stack?

Overview of the Technology Stack

• Jekyll: A static site generator built in Ruby, perfect for blogs and documentation.
• Mediumish Theme: A clean, minimalist theme inspired by Medium.com, optimized for readability and SEO.
• GitHub Pages: Free web hosting directly from your GitHub repository, with native support for Jekyll.

This combination eliminates traditional CMS issues, reduces maintenance, and offers a version-controlled content workflow—all at no cost.

Benefits of This Setup

• No more plugin conflicts or security updates.
• Lightning-fast page loading via CDN-powered static delivery.
• Free and automatic hosting via GitHub Pages.
• Markdown-based writing for simple and distraction-free publishing.

How to Prepare for the Migration

1. Audit Your Existing WordPress Content

Start by listing all your posts, pages, categories, and media. This audit will help you understand the scope of what needs to be migrated. Tools like WP All Export or simple CSV exports are useful here.

2. Export WordPress Content

Use the built-in WordPress Export Tool to generate an XML file. For greater control, consider plugins like "Jekyll Exporter" which converts your posts and metadata directly into Jekyll-ready format.

3. Convert to Markdown

Jekyll uses Markdown for content. You’ll need to convert the exported posts into Markdown files (`.md`) with YAML front matter. Tools like pandoc or wpxml2jekyll can automate this task.

How to Set Up the Mediumish Theme on GitHub Pages

Step-by-Step Guide

1. Fork the Mediumish theme: Start with a clean copy from GitHub. Make sure it supports GitHub Pages out of the box.
2. Clone to your machine: Use Git to clone the repository locally.
3. Customize site details: Edit _config.yml to include your site’s title, author name, and URL settings.
4. Add your content: Place your converted Markdown posts inside the _posts folder.
5. Push to GitHub: Commit your changes and push them back to your GitHub repository.
6. Activate GitHub Pages: Go to the repository settings and enable GitHub Pages from the main branch or the `/docs` folder, depending on your setup.

How to Handle SEO and Metadata During Migration

Preserve SEO Rankings

WordPress sites typically have structured permalinks, metadata, and internal linking strategies. You need to replicate this in Jekyll.

Set Up Permalinks

In _config.yml, define permalink formats to match your WordPress URLs as closely as possible. Example:

permalink: /:categories/:title/

Maintain Meta Descriptions and Tags

Each post’s front matter should include metadata such as title, description, tags, and categories. This is crucial for preserving your SEO value.

How to Add Features Without Plugins

Replacing Common WordPress Plugins

• SEO: Use Liquid templates to insert meta tags dynamically.
• Analytics: Embed Google Analytics tracking code in _includes/head.html.
• Comments: Integrate Disqus or use GitHub Issues as a comment system.
• Contact Forms: Use Formspree or Netlify Forms with custom HTML.

Optimizing for Performance

With no backend, performance mostly depends on static assets. Compress images, use minimal CSS and JavaScript, and enable caching headers using GitHub’s default CDN.

How to Manage Content After Migration

Writing New Posts

Write new content in Markdown, save it inside the _posts folder, and follow the correct naming convention: YYYY-MM-DD-title.md.

Version Control with Git

Every change to your site is now tracked via Git. This means you can revert errors, experiment with branches, and collaborate more efficiently than you ever could in WordPress.

Using GitHub Desktop

If you're not comfortable with the terminal, GitHub Desktop provides a user-friendly way to manage your repo, write commits, and push changes to GitHub.

Common Issues and How to Fix Them

Liquid Errors

Most errors in Jekyll come from improperly formatted Liquid code. Validate all your include tags, variable names, and conditions.

Theme Compatibility

Ensure the version of the Mediumish theme you are using is updated and maintained. Forking an outdated version might result in missing features or GitHub Pages compatibility issues.

Broken Internal Links

When moving from WordPress to Jekyll, check all internal links. Use site-wide search tools or link checkers to identify and fix broken links.

Is the Move Worth It in the Long Run?

For most tech-savvy users, absolutely. The performance gains, cost savings, and security improvements alone are worth the switch. But it comes with a learning curve. If you're comfortable editing text files and using Git, Jekyll offers a leaner, faster, and more reliable way to manage your content.

Key Takeaways

• Migrating from WordPress to Jekyll offers speed, security, and cost benefits.
• The Mediumish theme is a great starting point for clean and readable design.
• GitHub Pages provides free, reliable hosting with native Jekyll support.
• Migration involves content export, conversion, theming, and SEO preservation.
• Once migrated, your blog becomes easier to maintain and more scalable in the long term.

What's Next After Migrating?

After migration, you can further enhance your site with search integration, newsletters, or even headless CMS if needed. Keep your content updated by managing it through Git, and continue growing your site with confidence, knowing you’re no longer tied to a bloated CMS or expensive hosting.