Convert Eleventy Site to WordPress: A Step-by-Step Technical Guide

Why Convert Your Eleventy Site to WordPress?

Eleventy excels at generating fast, secure static sites, offering a lean development experience. However, its static nature can present challenges for non-technical content creators or when a more dynamic, user-manageable backend is required. WordPress, despite its reputation for being heavier, offers unparalleled content management system (CMS) features, a vast plugin ecosystem, and a familiar interface for many users.

The decision to convert often stems from a need for features like user management, e-commerce integration, advanced forms, or the desire to empower a team of content editors who are not comfortable with Markdown or static site generators. Migrating to WordPress provides a robust, extensible platform that can scale with evolving business needs, offering a balance between the performance benefits of a well-optimized theme and the flexibility of a dynamic CMS. This transition is less about replacing Eleventy and more about integrating its design principles into a more content-rich environment.

Understanding the Core Conversion Strategy: From Static HTML to Dynamic Theme

The fundamental strategy for converting an Eleventy site to WordPress is to take the final, rendered HTML and CSS output from your Eleventy build process and transform it into a functional WordPress theme. This means creating a set of WordPress template files (like `index.php`, `header.php`, `footer.php`, `page.php`, `single.php`, etc.) that mimic the structure of your Eleventy-generated pages.

Instead of hardcoding content, these WordPress template files will use PHP functions and the WordPress Loop to dynamically pull content from the WordPress database. Your Eleventy CSS and JavaScript will be enqueued correctly within the new WordPress theme. This approach ensures that the visual design and frontend interactivity of your original site are preserved while integrating seamlessly with WordPress's backend.

This is a manual, code-intensive process, but it ensures fidelity to your original design. You will essentially be reverse-engineering your static output into a dynamic structure.

Step 1: Preparing Your Eleventy Site for Conversion

Before you begin coding your WordPress theme, it's crucial to have a clean, final build of your Eleventy site. This build will serve as your blueprint. Ensure that all dependencies are resolved and the site functions perfectly in its static form.

This preparation phase is critical for identifying all unique layouts, component structures, and content types that will need to be replicated or mapped in WordPress. It allows you to anticipate the necessary WordPress template files and custom post types (CPTs) you'll need.

Consider using a tool to 'crawl' your Eleventy site's final output and generate a sitemap or list of all URLs. This list will be invaluable during content migration to ensure no pages are missed.

For a streamlined approach to grabbing the frontend code, you might consider using a browser extension like Themify.io. It can convert any live webpage into a downloadable WordPress theme. This can significantly accelerate the initial theme scaffolding by capturing the HTML, CSS, and JS directly from your rendered Eleventy site, giving you a strong starting point for the WordPress theme files you'll then customize to be dynamic. While it won't handle content migration, it's a powerful shortcut for the design layer.

This process also involves examining your Eleventy site for any dynamic elements that were handled by JavaScript. These will need to be re-implemented using WordPress's JavaScript enqueueing methods or suitable WordPress plugins.

Step 2: Creating Your Basic WordPress Theme Structure

Start by setting up a fresh WordPress installation. Navigate to `wp-content/themes/` and create a new folder for your theme (e.g., `my-eleventy-theme`). Inside this folder, you need at least two essential files:

The `style.css` file is mandatory and provides basic information about your theme. It also serves as the main stylesheet. The `index.php` file is the fallback template for displaying posts if no more specific template is found.

The `functions.php` file is where you'll register styles, scripts, custom post types, and other theme-specific functionalities. It's the powerhouse of your theme.

You'll also want to create `header.php` and `footer.php` files. These files will contain the common elements of your Eleventy site's header and footer sections, and they will be included in other template files using `get_header()` and `get_footer()`.

Finally, create a `screenshot.png` (1200px by 900px recommended) to represent your theme in the WordPress Appearance menu.

• File: `style.css`
• Required Header: `Theme Name: My Eleventy Theme`, `Author: Your Name`, `Version: 1.0`, `Text Domain: my-eleventy-theme`
• File: `index.php`
• File: `functions.php`
• File: `header.php`
• File: `footer.php`
• File: `screenshot.png`

Step 3: Integrating Eleventy's HTML, CSS, and JavaScript into WordPress

This is where you start bringing your Eleventy design to life within WordPress. Open your Eleventy site's generated `index.html` (or similar main layout file) and start dissecting it.

Copy the HTML from your Eleventy site's main layout (excluding `<body>` and `</body>` tags) into `header.php` and `footer.php`. The content *between* the header and footer (i.e., the main content area) will go into `index.php` and other specific template files.

Replace static content with dynamic WordPress functions. For instance, replace `<title>My Static Site</title>` in `header.php` with `<title><?php wp_title(''); ?></title>`. The Eleventy build includes `<div id="root">...</div>` or similar content wrappers; these will now house `the_content()`.

Copy all your Eleventy-generated CSS files into a `css` subfolder within your theme and all JavaScript files into a `js` subfolder. Then, enqueue them properly in `functions.php`:

Make sure your `functions.php` includes proper enqueueing for all styles and scripts. For example, for a main stylesheet and a JavaScript bundle:

Replace any hardcoded image paths in your CSS or HTML with `<?php echo get_template_directory_uri(); ?>/path/to/image.jpg` to ensure they point to the correct theme directory.

1. **Copy HTML Structure:** Take the `<head>` content from your Eleventy's `_site/index.html` and place it in your theme's `header.php`, making sure to replace `<title>` and other dynamic elements with WordPress functions. For example, replace `<title>Your Eleventy Site</title>` with `<title><?php wp_title(''); ?></title>`. Place the opening `<body>` tag here.
2. **Integrate Body & Content:** Copy the closing `</body>` and `</html>` tags into `footer.php`. In `header.php`, just before the closing `</head>` tag, add `<?php wp_head(); ?>`. In `footer.php`, just before the closing `</body>` tag, add `<?php wp_footer(); ?>`. These are crucial for WordPress to inject its own scripts and styles.
3. **Main Content Loop:** In your `index.php` file, wrap your primary content area with the WordPress Loop. For a basic page, it would look like: `<?php get_header(); ?> <div class="container"> <?php if (have_posts()) : while (have_posts()) : the_post(); ?> <?php the_content(); ?> <?php endwhile; endif; ?> </div> <?php get_footer(); ?>`. You'll refine this for posts, pages, etc.
4. **Enqueue Styles and Scripts:** In your `functions.php` file, add the following to properly load your CSS and JavaScript files from your theme's `css` and `js` subdirectories:
5. ```php function my_eleventy_theme_scripts() { wp_enqueue_style('my-eleventy-style', get_template_directory_uri() . '/css/style.css', array(), '1.0', 'all'); wp_enqueue_script('my-eleventy-script', get_template_directory_uri() . '/js/main.js', array('jquery'), '1.0', true); } add_action('wp_enqueue_scripts', 'my_eleventy_theme_scripts); ```

Step 4: Migrating Content from Eleventy to WordPress

Content migration is often the most tedious part of the process. If your Eleventy content was primarily Markdown files (`.md`), you'll need to manually copy and paste this content into the WordPress editor, or use a script to automate the process.

For a small number of pages, manual migration is feasible. For larger sites, consider scripting the process. You can write a PHP, Python, or Node.js script to read your Eleventy Markdown files, parse them, and then use the WordPress REST API to create posts or pages programmatically. This method requires a good understanding of the WordPress REST API and authentication.

When migrating, pay close attention to internal links. Static relative links (e.g., `/about/`) will break. You'll need to update them to use WordPress's dynamic link functions like `get_permalink()` or rely on a 'Search and Replace' plugin after migration to update all internal URLs to their WordPress equivalents.

Images and other media assets also need to be migrated. Upload them to your WordPress Media Library, and then update their paths in your content. If you've used a CDN for your Eleventy assets, ensure that arrangement is replicated or redirected in WordPress.

• **Manual Copy/Paste:** For small sites (under 50 pages/posts), directly copy content from your Eleventy Markdown files into the WordPress Gutenberg editor.
• **Scripted Migration:** For larger sites, develop a script (e.g., Python, Node.js) to read Eleventy `.md` files, convert Markdown to HTML, and post to WordPress via the REST API (`wp-json/wp/v2/posts`).
• **Media Migration:** Upload all images and other media assets to your WordPress Media Library. Update image paths in your content to reflect the new WordPress URLs.
• **Internal Link Management:** Replace hardcoded relative links with dynamic WordPress links (`<?php echo get_permalink(get_page_by_path('your-slug')->ID); ?>`) or perform a global search-and-replace after migration using a plugin like "Better Search Replace".

Step 5: Refining Templates for Posts, Pages, and Archives

After getting `index.php` and your basic content running, you'll need to create more specific WordPress templates to handle different content types, much like you would have different layouts in Eleventy.

For individual posts, create `single.php`. For static pages, use `page.php`. For categories or tags, use `category.php` and `tag.php`. Each of these files will leverage `get_header()`, `get_footer()`, and `the_content()` but might have unique layouts or additional WordPress Loop queries.

If your Eleventy site used custom content types (e.g., `projects`, `products`), you'll need to register Custom Post Types (CPTs) in your `functions.php` file. Then, create corresponding template files like `archive-project.php` and `single-project.php` to display them.

This is also the stage where you'll implement comments if your Eleventy site had them (e.g., via a third-party service like Disqus) or if you want to add native WordPress comments using `comments_template()`.

Take the time to replicate the exact structure and classes of your Eleventy layouts for these specific templates to ensure consistent styling. This includes setting up custom fields if your Eleventy content had front matter that maps to specific data points beyond the main content body. You could use plugins like Advanced Custom Fields (ACF) to manage this data.

• **`single.php`:** For individual blog posts.
• **`page.php`:** For static pages.
• **`archive.php`:** For category, tag, and date archives.
• **`search.php`:** For search results.
• **Custom Post Types (CPTs):** If your Eleventy site had custom content, register CPTs in `functions.php` and create `archive-{cpt}.php` and `single-{cpt}.php` templates.
• **Custom Fields:** Implement custom fields using `get_post_meta()` or a plugin like ACF to display Eleventy front matter data.

Step 6: Post-Conversion Testing and Optimization

Once your site is running on WordPress, rigorous testing is paramount. Verify all pages, posts, images, and internal links function correctly. Test forms, navigation, and any interactive elements.

**Performance Optimization:** Eleventy sites are inherently fast. To maintain comparable performance in WordPress, focus on optimization: implement caching (e.g., WP Super Cache, LiteSpeed Cache), optimize images (Smush, Imagify), and use a CDN. Analyze your site with tools like Google PageSpeed Insights and GTmetrix.

**Security:** WordPress requires more attention to security than a static site. Keep WordPress core, themes, and plugins updated. Use a security plugin (e.g., Wordfence, Sucuri) and strong passwords.

**SEO Considerations:** Ensure your permalinks are SEO-friendly (`Settings -> Permalinks`). Implement an SEO plugin (e.g., Yoast SEO, Rank Math) to manage meta titles, descriptions, and sitemaps. Redirect any old Eleventy URLs that might have changed during migration to their new WordPress equivalents using 301 redirects, to preserve SEO value.

**Backup Strategy:** Establish a robust backup strategy for your WordPress site, including both the database and files. Solutions like UpdraftPlus or your web host's backup service are essential.

The conversion from Eleventy to WordPress is a significant undertaking, but with careful planning and execution, you can successfully transition to a more flexible and feature-rich platform while preserving your site's aesthetic and functionality. Remember that the initial output from a tool like Themify, while providing a great visual starting point, will need to be made dynamic to truly leverage WordPress's CMS capabilities.