How i migrated my blog from wordpress to a static site with jekyll and github pages

2120 words

11 minutes

How i migrated my blog from wordpress to a static site with jekyll and github pages

2025-06-26

Tutorial

Jekyll

/

WordPress

/

Static Sites

/

Blogging

/

Web Development

Migrating a blog from a dynamic Content Management System (CMS) like WordPress to a static site built with Jekyll and hosted on GitHub Pages involves transforming database-driven content into pre-rendered HTML files. This process offers significant advantages in terms of performance, security, and cost-efficiency for many types of websites, particularly blogs and documentation sites.

The transition moves away from the traditional WordPress architecture, which relies on a server-side language (PHP) and a database (MySQL) to generate pages on demand for each visitor request. A static site, conversely, consists of flat HTML, CSS, and JavaScript files that are served directly by the web server without any server-side processing.

Jekyll is a popular static site generator that takes plain text content written in formats like Markdown, applies templates, and produces a complete, ready-to-serve static website. GitHub Pages is a service that directly hosts static websites from a GitHub repository, offering free hosting and seamless integration with Jekyll.

Why Migrate from WordPress to a Static Site?#

Blog owners and developers often consider migrating from WordPress to a static setup for several compelling reasons:

Performance: Static sites load significantly faster than dynamic sites. There’s no database lookup or server-side computation needed; the server simply sends the pre-built HTML file. This leads to better user experience and improved search engine ranking, as site speed is a known ranking factor.
Security: Static sites have a much smaller attack surface compared to dynamic CMS platforms like WordPress. Without a database, PHP processing, themes, and plugins that are common targets for exploits, the risk of security breaches is drastically reduced. Updates are less frequent and less critical from a security standpoint.
Cost: GitHub Pages offers free hosting for public repositories. This eliminates monthly hosting fees often associated with WordPress sites that require a database and PHP environment. For sites with moderate traffic, this can represent substantial savings.
Simplicity: Managing a static site eliminates the complexities of database backups, WordPress core updates, plugin updates, and theme compatibility issues that often consume time and resources.
Scalability: Static sites handle traffic spikes effortlessly because they serve simple files. Content Delivery Networks (CDNs) can cache these files easily, providing excellent global reach and scalability without complex server configurations.

Understanding the Key Technologies#

Successful migration requires familiarity with the core components:

WordPress (Dynamic CMS): WordPress stores content in a MySQL database and uses PHP scripts to query the database, retrieve content, combine it with template files, and generate HTML output when a user visits a page. This flexibility allows for dynamic features but adds overhead and potential security vulnerabilities.
Static Sites: These websites consist entirely of static files (HTML, CSS, JS, images). Pages are built before a user requests them. When a request arrives, the server simply sends the pre-rendered file.
Jekyll: A static site generator written in Ruby. It processes input files (Markdown, Liquid templates, HTML), applies layouts and includes, and outputs a complete static website ready for deployment. Jekyll is folder-based, with conventions for posts (_posts), pages, layouts (_layouts), includes (_includes), and configuration (_config.yml).
GitHub Pages: A static site hosting service provided by GitHub. It can serve static files directly from a repository or build and serve Jekyll sites automatically. It integrates seamlessly with Jekyll, allowing deployment simply by pushing changes to a specific branch (often main or master).

The Migration Process: Step-by-Step Guide#

Migrating a blog from WordPress to a static site with Jekyll and GitHub Pages involves several distinct steps.

Step 1: Export WordPress Content#

The first step is to export the existing content from the WordPress site.

Access the WordPress admin dashboard.
Navigate to Tools > Export.
Select “All content” to export posts, pages, comments, custom fields, navigation menus, and custom posts.
Click “Download Export File”. This generates an XML file containing the blog’s content.

Step 2: Set up the Local Development Environment#

Jekyll requires a local environment to build the site.

Install Ruby: Jekyll is a Ruby gem. Ruby must be installed on the local machine. Installation methods vary by operating system (e.g., using package managers like Homebrew on macOS, apt on Debian/Ubuntu, or installers on Windows). Using a Ruby version manager like rbenv or RVM is often recommended to manage multiple Ruby versions.
Install Bundler: Bundler is a Ruby gem manager. Install it using the command:
Terminal window
```
1
gem install bundler
```
Install Jekyll: Install Jekyll and the jekyll-import gem needed for the migration.
Terminal window
```
1
gem install jekyll bundler jekyll-import
```
Create a new Jekyll site: Navigate to the desired directory in the terminal and create a new Jekyll site:
Terminal window
```
1
jekyll new my-static-blog
2
cd my-static-blog
```
This creates a basic Jekyll site structure.

Step 3: Import WordPress Content into Jekyll#

Jekyll has importers to convert content from various platforms, including WordPress.

The jekyll-import gem is used for this purpose. The importer reads the WordPress XML export file and converts posts and pages into Markdown files formatted correctly for Jekyll.
Open the my-static-blog directory created in the previous step.

Create a configuration file for the import, for example, import.rb. The content of this file specifies the importer to use and the path to the XML file:

1
require 'jekyll-import'
2

3
JekyllImport::Importers::WordPress.run({
4
  'source' => 'path/to/your/wordpress-export.xml', # Update this path
5
  'no_fetch_assets' => false, # Set to true if you don't want to download images
6
  'asset_path' => 'assets/images', # Optional: specify path for downloaded assets
7
  'blog_name' => 'My Static Blog', # Optional: blog name
8
  'clean_entities' => true,
9
  'clean_urls' => true,
10
  'markdownify_in_html' => true,
11
  'sanitize_html' => false,
12
  'generate_excerpt' => true,
13
})

Execute the import using Bundler to ensure gems are handled correctly:
Terminal window
```
1
bundle exec ruby import.rb
```
This command processes the XML file and populates the _posts and _pages directories with Markdown files containing the imported content. Images might be downloaded depending on the no_fetch_assets setting.

Step 4: Configure Jekyll#

The primary configuration file for a Jekyll site is _config.yml located in the root directory.

Edit _config.yml to set site-wide variables and configurations.

Basic Settings: Set the site title, description, author, and base URL.

1
title: My Static Blog
2
description: A blog about interesting things.
3
author: Your Name
4
baseurl: "" # the subpath of your site, e.g. /blog
5
url: "https://yourusername.github.io" # the base hostname & protocol for your site

Permalinks: Define the URL structure for posts. A common and SEO-friendly structure is /year/month/day/post-title/.
```
1
permalink: /:year/:month/:day/:title/
```
Gems: Add necessary Jekyll plugins (gems) to the configuration. Common useful gems include jekyll-feed (for RSS feed), jekyll-seo-tag (for SEO metadata), and jekyll-sitemap (for sitemap generation). These need to be added to the Gemfile and installed with bundle install, and then listed in _config.yml:
```
1
plugins:
2
  - jekyll-feed
3
  - jekyll-seo-tag
4
  - jekyll-sitemap
5
  # Add other gems like jekyll-redirect-from here
```

Step 5: Choose and Customize a Theme#

Jekyll themes control the appearance of the static site.

Themes can be installed as Ruby gems or by copying theme files directly into the Jekyll project structure.
Explore Jekyll themes on sites like Jekyll Themes or GitHub.
If using a gem-based theme, add it to the Gemfile, run bundle install, and specify the theme name in _config.yml.
For more customization, copy theme files (layouts, includes, CSS) into the corresponding directories in the Jekyll project. Customize CSS files (/assets/css/), modify layout files (_layouts/), and adjust include files (_includes/) to match desired branding and structure.

Step 6: Review and Refine Content#

After import, thorough review of the converted content is essential.

Check Markdown Formatting: The importer attempts to convert HTML to Markdown, but manual adjustments may be needed for complex formatting, tables, or specific HTML elements. Review posts and pages in the _posts and _pages directories.
Handle Images: Ensure images are correctly referenced in posts and are present in the Jekyll project (typically in an assets/images or similar folder). If the importer didn’t download them, images need to be manually copied from the WordPress site’s wp-content/uploads directory.
Internal and External Links: Verify links within content are correct.
Set up Redirects: This is crucial for maintaining SEO and user experience. If the URL structure changes, set up redirects from the old WordPress URLs to the new Jekyll URLs. The jekyll-redirect-from gem is useful for this. Install the gem and add redirect_from: /old-wordpress-url/ to the front matter of the corresponding new post/page.
Create Essential Pages: Create or update pages like About, Contact, Privacy Policy, etc., using Markdown files in the root directory or a dedicated pages directory.

Step 7: Set up Git and GitHub Repository#

Version control and hosting on GitHub Pages require Git.

Initialize Git: In the root directory of the Jekyll project, initialize a Git repository:
Terminal window
```
1
git init
```
Add and Commit Files: Add the project files to the repository and create the initial commit:
Terminal window
```
1
git add .
2
git commit -m "Initial commit of Jekyll blog"
```
Create GitHub Repository: Go to GitHub, create a new repository. Name it username.github.io for a personal site served at username.github.io, or a project name if hosting under a subpath (e.g., username.github.io/project-name).
Link Local to Remote: Connect the local repository to the GitHub repository:
Terminal window
```
1
git remote add origin https://github.com/yourusername/yourrepositoryname.git
2
git branch -M main
3
git push -u origin main
```
(Replace yourusername and yourrepositoryname accordingly).

Step 8: Deploy with GitHub Pages#

GitHub Pages can automatically build and deploy Jekyll sites.

Navigate to the settings page of the GitHub repository.
Find the “Pages” section.
Select the branch (main or master) and folder (usually /root) from which to build the site.
Save the settings. GitHub Pages will initiate a build process. The site will typically become available at https://yourusername.github.io or https://yourusername.github.io/yourrepositoryname/ within a few minutes.
Custom Domain (Optional): To use a custom domain (e.g., example.com), add a CNAME file containing the custom domain to the root of the Jekyll project. Configure DNS records with the domain registrar to point to GitHub Pages.

Step 9: Post-Migration Tasks#

After deployment, several tasks ensure the site is functional and discoverable.

Testing: Thoroughly test the live site. Check all pages, posts, links, images, and navigation.
Analytics: Set up web analytics (e.g., Google Analytics) by adding the tracking code to the appropriate layout file (_layouts/default.html or similar).
Search Engine Optimization (SEO):
- Verify that the jekyll-seo-tag gem is correctly configured in _config.yml and layout files to generate appropriate meta tags, titles, and canonical URLs.
- Ensure the jekyll-sitemap gem is generating a sitemap.xml file.
- Submit the sitemap to Google Search Console, Bing Webmaster Tools, etc.
- If redirects were implemented (Step 6), test them using online redirect checkers.
Comments: Static sites don’t have native comment systems. Integrate a third-party commenting service like Disqus, Isso, or use a system built on GitHub Issues (like Utterances or giscus). This involves adding the service’s code snippet to the post layout.
Performance Monitoring: Use tools like Google PageSpeed Insights, GTmetrix, or WebPageTest to monitor site performance and identify areas for further optimization (e.g., image compression).

SEO Considerations for Jekyll on GitHub Pages#

Static sites built with Jekyll and hosted on GitHub Pages have inherent advantages for SEO, but specific configurations are still required.

Site Speed: The static nature provides a strong foundation for fast loading times, a critical SEO factor.
Mobile-Friendliness: Depends on the chosen Jekyll theme. Modern themes are typically responsive.
SSL: GitHub Pages provides free HTTPS for all sites, which is a positive SEO signal.
Permalinks: Configurable permalinks (_config.yml) allow creating descriptive and SEO-friendly URLs. Consistency with old URLs (via redirects) is vital.
Meta Tags: Using gems like jekyll-seo-tag ensures correct title tags, meta descriptions, Open Graph tags, and Twitter Cards are automatically generated based on content and site configuration.
Sitemaps: The jekyll-sitemap gem generates an sitemap.xml file, helping search engines discover all pages on the site.
Content Quality: As with any site, high-quality, relevant, and well-structured content remains the most significant factor for SEO success.

Challenges and Considerations#

While advantageous, migrating to Jekyll and GitHub Pages presents potential challenges:

Technical Learning Curve: This process requires comfort with the command line, Git, Markdown, and basic file structure concepts. It is less user-friendly than the WordPress admin dashboard for everyday content creation or site management.
Feature Limitations: Static sites are best suited for content that doesn’t change frequently or require complex server-side interactions (user accounts, e-commerce transactions, advanced forms). These features typically need integration with external services.
Theme Customization: Significant theme modifications often require knowledge of HTML, CSS, Liquid templating, and potentially Sass.

Key Takeaways and Actionable Insights#

Migrating a blog from WordPress to a static site using Jekyll and GitHub Pages offers significant benefits, particularly in performance, security, and cost.

Benefits: Static sites are inherently faster, more secure, and can be hosted for free on GitHub Pages.
Core Tools: The process relies on exporting content from WordPress, using Jekyll as a static site generator, and hosting on GitHub Pages. Familiarity with Git and Markdown is necessary.
Migration Steps: The process involves exporting content, setting up the Jekyll environment, importing content using jekyll-import, configuring Jekyll (_config.yml), choosing and customizing a theme, meticulously reviewing and refining content (especially images and links), setting up Git and deploying to GitHub Pages, and completing post-launch tasks like analytics and SEO verification.
Essential Configurations: Key configurations include setting site details, defining permalinks, and adding necessary gems (jekyll-seo-tag, jekyll-sitemap, jekyll-redirect-from, jekyll-feed).
Content Review: The most time-consuming part often involves cleaning up imported Markdown, ensuring image paths are correct, and setting up redirects for changed URLs.
SEO Best Practices: Leverage the inherent speed advantage, configure meta tags and sitemaps using Jekyll gems, and ensure proper redirects are in place.
Consider the Trade-offs: While powerful, the static approach requires more technical comfort and is less suited for sites needing complex dynamic features or frequent non-technical content updates.