Static Site Exporter

Using WP-CLI

The easiest way to perform selective exports is via WP-CLI commands.

Export by Category

To export posts from a single category, use the category slug:

`bash

wp jekyll-export –category=technology > technology-export.zip `

To export from multiple categories (OR logic – posts in any of these categories):

`bash

wp jekyll-export –category=tech,news,updates > export.zip `

Export by Tag

To export posts with a specific tag:

`bash

wp jekyll-export –tag=featured > featured-export.zip `

To export posts with multiple tags (OR logic):

`bash

wp jekyll-export –tag=featured,popular > export.zip `

Export Specific Post Types

To export only pages:

`bash

wp jekyll-export –post_type=page > pages-export.zip `

To export only posts:

`bash

wp jekyll-export –post_type=post > posts-export.zip `

To export custom post types:

`bash

wp jekyll-export –post_type=portfolio,testimonial > custom-export.zip `

Combining Filters

You can combine multiple filters. Posts must match ALL specified filters (AND logic):

`bash<h3>Export posts that are in "technology" category AND have "featured" tag</h3>wp jekyll-export --category=technology --tag=featured --post_type=post > export.zip `<h3>Using PHP Filters</h3>

For more programmatic control, you can use WordPress filters directly in your theme’s functions.php or a custom plugin.

Filter by Category

`php

add_filter( ‘jekyll_export_taxonomy_filters’, function() { return array( ‘category’ => array( ‘technology’, ‘science’ ), ); } ); `

Filter by Tag

`php

add_filter( ‘jekyll_export_taxonomy_filters’, function() { return array( ‘post_tag’ => array( ‘featured’, ‘popular’ ), ); } ); `

Filter by Custom Taxonomy

`php

add_filter( ‘jekyll_export_taxonomy_filters’, function() { return array( ‘my_custom_taxonomy’ => array( ‘term-slug-1’, ‘term-slug-2’ ), ); } ); `

Combine Multiple Taxonomies

`php

add_filter( ‘jekyll_export_taxonomy_filters’, function() { return array( ‘category’ => array( ‘technology’ ), ‘post_tag’ => array( ‘featured’ ), ‘custom_tax’ => array( ‘term-1’ ), ); } ); `

Filter Post Types

`php

add_filter( ‘jekyll_export_post_types’, function() { return array( ‘post’, ‘page’ ); // Only export posts and pages } ); `

Finding Category and Tag Slugs

If you’re not sure what slug to use:

Via WordPress Admin

1. 04Go to Posts > Categories or Posts > Tags
2. 05Hover over the category/tag name
3. 06Look at the browser’s status bar or the URL – you’ll see something like tag_ID=123&taxonomy=post_tag&term_slug=featured
4. 07The slug is the part after term_slug=

Via WP-CLI

List all categories with their slugs:

`bash

wp term list category –fields=name,slug `

List all tags with their slugs:

`bash

wp term list post_tag –fields=name,slug `

Use Cases

Scenario 1: Export a Single Blog Section

You have a WordPress site with multiple sections (Tech, Lifestyle, Travel) and want to move just the Tech section to a static site:

`bash

wp jekyll-export –category=tech > tech-blog-export.zip `

Scenario 2: Export Featured Content

You want to export only posts marked as “featured” for a special showcase site:

`bash

wp jekyll-export –tag=featured > featured-content.zip `

Scenario 3: Export by Year (using custom taxonomy)

If you’ve tagged posts by year, you can export by year:

`bash

wp jekyll-export –tag=2024 > 2024-posts.zip `

Scenario 4: Migrate Content Incrementally

Export different categories separately for incremental migration:

`bash

wp jekyll-export –category=tech > tech.zip wp jekyll-export –category=news > news.zip wp jekyll-export –category=reviews > reviews.zip `

Technical Details

• Taxonomy Filtering : Uses WordPress term slugs (not names or IDs)
• Query Performance : Filtering is done at the database level for efficiency
• OR Logic Within Taxonomy : Multiple terms in the same taxonomy use OR logic (e.g., posts in category A OR B)
• AND Logic Across Taxonomies : Multiple taxonomies use AND logic (e.g., posts in category A AND having tag B)
• Post Type Filtering : Works independently of taxonomy filtering

Limitations

• Revisions are excluded when using taxonomy filters (as they don’t have taxonomy terms)
• Taxonomy filtering uses term slugs, not term IDs or names
• Empty taxonomy filters are ignored (no filtering applied)

Troubleshooting

No Posts Exported

If your export is empty:

1. 08Check the slug : Make sure you’re using the term slug, not the name Use wp term list category to verify the exact slug
2. 09Check post status : Only published, future, and draft posts are exported
3. 10Verify taxonomy : Make sure you’re using the correct taxonomy name ( category , post_tag , etc.)

Wrong Posts Exported

If you’re getting unexpected posts:

1. 11Check term associations : Verify which posts have the category/tag assigned
2. 12Review filter logic : Remember that multiple categories use OR logic
3. 13Clear cache : If testing, use wp cache flush between exports

Custom post types

To export custom post types, you’ll need to add a filter (w.g. to your themes config file) to do the following:

`php

add_filter( ‘jekyll_export_post_types’, function() { return array(‘post’, ‘page’, ‘you-custom-post-type’); }); `

The custom post type will be exported as a Jekyll collection. You’ll need to initialize it in the resulting Jekyll site’s _config.yml .

Developing locally

Option 1: Using Dev Containers (Recommended)

The easiest way to get started is using VS Code Dev Containers or GitHub Codespaces :

1. 14Install VS Code and the Dev Containers extension
2. 15git clone https://github.com/benbalter/wordpress-to-jekyll-exporter
3. 16Open the folder in VS Code
4. 17Click “Reopen in Container” when prompted
5. 18Wait for the container to build and dependencies to install
6. 19Access WordPress at http://localhost:8088

The devcontainer includes: – Pre-configured WordPress and MySQL – All PHP extensions and Composer dependencies – VS Code extensions for PHP development, debugging, and testing – WordPress coding standards configured

See .devcontainer/README.md for more details.

Option 2: Manual Setup

Prerequisites

1. 20sudo apt-get update
2. 21sudo apt-get install composer
3. 22sudo apt-get install php7.3-xml
4. 23sudo apt-get install php7.3-mysql
5. 24sudo apt-get install php7.3-zip
6. 25sudo apt-get install php-mbstring
7. 26sudo apt-get install subversion
8. 27sudo apt-get install mysql-server
9. 28sudo apt-get install php-pear
10. 29sudo pear install PHP_CodeSniffer

Bootstrap & Setup

1. 30git clone https://github.com/benbalter/wordpress-to-jekyll-exporter
2. 31cd wordpress-to-jekyll-exporter
3. 32script/bootstrap
4. 33script/setup

Option 3: Docker Compose Only

1. 34git clone https://github.com/benbalter/wordpress-to-jekyll-exporter
2. 35docker-compose up
3. 36open localhost:8088

Running tests

script/cibuild<h3>Custom fields</h3>

When using custom fields (e.g. with the Advanced Custom fields plugin) you might have to register a filter to convert array style configs to plain values.

Available Filters

The plugin provides two filters for customizing post metadata:

• jekyll_export_meta : Filters the metadata for a single post before it’s merged with taxonomy terms. Receives $meta array and $post object as parameters.
• jekyll_export_post_meta : Filters the complete metadata array (including taxonomy terms) just before it’s written to the YAML frontmatter. Receives $meta array and $post object as parameters. This is the recommended filter for most use cases.

Note: As of the latest version, the plugin no longer automatically removes empty or falsy values from the frontmatter. All metadata is preserved by default. If you want to remove certain fields, you can use the jekyll_export_post_meta filter to customize this behavior.