{"active_installs":500,"added":{"timestamp":1418342400,"timezone":"UTC"},"author":"Ben Balter","author_profile":{"url":"https://profiles.wordpress.org/benbalter/","alt":"Ben Balter"},"banners":[{"type":"high","url":"https://ps.w.org/jekyll-exporter/assets/banner-1544x500.png?rev=3073421"},{"type":"low","url":"https://ps.w.org/jekyll-exporter/assets/banner-772x250.png?rev=3073421"}],"changelog":"

4.0.4

Stream the export zip to the browser in 8 KB chunks instead of loading the entire archive into memory in send(), so large exports no longer hit memory_limit after a successful build
zip_folder() now throws RuntimeException instead of calling wp_die() directly, so the existing export() try/catch renders a friendly error and runs cleanup() on partial temp files
Added jekyll_export_html_converter filter so integrations (and tests) can swap in a custom HTML-to-Markdown converter
Gated the v4.0.3 fallback error_log() call behind WP_DEBUG
Hardened sanitization of $_GET['type'] in the export callback
Added regression tests for the v4.0.3 Invalid HTML was provided fallback and for the new zip_folder() throw behavior

4.0.3

Catch InvalidArgumentException from league/html-to-markdown in convert_content() and fall back to the post’s raw HTML for that single post instead of aborting the entire export with “Jekyll Export failed: Invalid HTML was provided” (#400)

4.0.2

Add shutdown handler to surface fatal errors (memory exhaustion, max execution time) during export with actionable error messages instead of a generic WordPress critical error page
Add proactive memory_limit pre-flight check (warns when below 64MB) in validate_environment()
Display admin error notice on Tools → Export when environment validation fails, before the user clicks Export

4.0.1

Security: Use cryptographically secure randomness (wp_generate_password) instead of md5(time()) for the export temp directory name to prevent symlink/TOCTOU attacks on shared hosts (CWE-330/377)
Security: Reject non-CLI access in deprecated jekyll-export-cli.php before bootstrapping WordPress (CWE-665)
Security: Sanitize each path segment of page filenames as defense-in-depth against path traversal (CWE-22)
Fix stale $upload_basedir cache in copy_recursive() on multisite by keying it on the current blog ID

4.0.0

Breaking: Minimum PHP version bumped from 7.2.5 to 8.2
Breaking: Minimum WordPress version bumped from 4.4 to 6.4
Updated symfony/yaml from ^5.4 to ^7.0
Updated PHPUnit from ~8.0 to ~9.6
Removed symfony/polyfill-php80 (no longer needed)
Added PHPStan static analysis at level 5
Fixed get_posts() to return integer IDs instead of strings
Fixed PHPDoc type annotations throughout codebase
Deprecated legacy jekyll-export-cli.php in favor of lib/cli.php
Improved CI pipeline with PHPStan job and vendor consistency checks

View Past Releases

\n","contributors":[{"slug":"benbalter","name":"Ben Balter","count":8,"is_owner":true,"links":{"profile":{"url":"https://profiles.wordpress.org/benbalter/","alt":"Ben Balter's profile"},"plugins":{"url":"https://profiles.wordpress.org/benbalter/#content-plugins","alt":"Ben Balter's plugins"},"activity":{"url":"https://profiles.wordpress.org/benbalter/#content-activity","alt":"Ben Balter's activity"},"translations":{"url":"https://profiles.wordpress.org/benbalter/#content-translations","alt":"Ben Balter's translations"}}},{"slug":"benbalter","name":"Ben Balter","count":2,"is_owner":false,"links":{"profile":{"url":"https://profiles.wordpress.org/benbalter/","alt":"Ben Balter's profile"},"plugins":{"url":"https://profiles.wordpress.org/benbalter/#content-plugins","alt":"Ben Balter's plugins"},"activity":{"url":"https://profiles.wordpress.org/benbalter/#content-activity","alt":"Ben Balter's activity"},"translations":{"url":"https://profiles.wordpress.org/benbalter/#content-translations","alt":"Ben Balter's translations"}}}],"description":"

Features

Converts all posts, pages, and settings from WordPress to Markdown and YAML for use in Jekyll (or Hugo or any other Markdown and YAML based site engine)
Export what your users see, not what the database stores (runs post content through the_content filter prior to export, allowing third-party plugins to modify the output)
Converts all post_content to Markdown
Converts all post_meta and fields within the wp_posts table to YAML front matter for parsing by Jekyll
Generates a _config.yml with all settings in the wp_options table
Outputs a single zip file with _config.yml, pages, and _posts folder containing .md files for each post in the proper Jekyll naming convention
Selective export: Export only specific categories, tags, or post types using WP-CLI
No settings. Just a single click.

Usage

Place plugin in /wp-content/plugins/ folder
Activate plugin in WordPress dashboard
Select Export to Jekyll from the Tools menu

More information

See the full documentation:

Selective Export by Category or Tag

This feature allows you to export only a specific subset of your WordPress content, filtered by category, tag, or post type. This is particularly useful when:

You have a large WordPress site but only need to convert specific sections
You want to migrate content by topic or category
You need to export content incrementally

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\n

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

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

`bash\n

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

Export by Tag

To export posts with a specific tag:

`bash\n

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

To export posts with multiple tags (OR logic):

`bash\n

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

Export Specific Post Types

To export only pages:

`bash\n

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

To export only posts:

`bash\n

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

To export custom post types:

`bash\n

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

Combining Filters

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

`bashExport posts that are in \"technology\" category AND have \"featured\" tag
wp jekyll-export --category=technology --tag=featured --post_type=post > export.zip\n`Using PHP Filters
\n

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

Filter by Category

`php\n

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

Filter by Tag

`php\n

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

Filter by Custom Taxonomy

`php\n

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

Combine Multiple Taxonomies

`php\n

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

Filter Post Types

`php\n

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

Finding Category and Tag Slugs

If you’re not sure what slug to use:

Via WordPress Admin

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

Via WP-CLI

List all categories with their slugs:

`bash\n

wp term list category –fields=name,slug
\n `

List all tags with their slugs:

`bash\n

wp term list post_tag –fields=name,slug
\n `

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\n

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

Scenario 2: Export Featured Content

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

`bash\n

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

Scenario 3: Export by Year (using custom taxonomy)

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

`bash\n

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

Scenario 4: Migrate Content Incrementally

Export different categories separately for incremental migration:

`bash\n

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

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:

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

Wrong Posts Exported

If you’re getting unexpected posts:

Check term associations: Verify which posts have the category/tag assigned
Review filter logic: Remember that multiple categories use OR logic
Clear 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\n

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

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:

Install VS Code and the Dev Containers extension
git clone https://github.com/benbalter/wordpress-to-jekyll-exporter
Open the folder in VS Code
Click “Reopen in Container” when prompted
Wait for the container to build and dependencies to install
Access WordPress at http://localhost:8088

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

See .devcontainer/README.md for more details.

Option 2: Manual Setup

Prerequisites

sudo apt-get update
sudo apt-get install composer
sudo apt-get install php7.3-xml
sudo apt-get install php7.3-mysql
sudo apt-get install php7.3-zip
sudo apt-get install php-mbstring
sudo apt-get install subversion
sudo apt-get install mysql-server
sudo apt-get install php-pear
sudo pear install PHP_CodeSniffer

Bootstrap & Setup

git clone https://github.com/benbalter/wordpress-to-jekyll-exporter
cd wordpress-to-jekyll-exporter
script/bootstrap
script/setup

Option 3: Docker Compose Only

git clone https://github.com/benbalter/wordpress-to-jekyll-exporter
docker-compose up
open localhost:8088

Running tests

script/cibuildCustom fields
\n

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 as the only parameter.
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.

By default, the plugin saves custom fields in an array structure that is exported as:

`php\n

[“my-bool”]=>
\n array(1) {
\n [0] => string(1) “1”
\n }
\n[“location”]=>
\n array(1) {
\n [0] => string(88) “My address”
\n }
\n `

And this leads to a YAML structure like:

`yaml\n

my-bool:
\n– “1”
\nlocation:
\n– ‘My address’
\n `

This is likely not the structure you expect or want to work with. You can convert it using a filter:

`php\n

add_filter( ‘jekyll_export_meta’, function($meta) {
\n foreach ($meta as $key => $value) {
\n if (is_array($value) && count($value) === 1 && array_key_exists(0, $value)) {
\n $meta[$key] = $value[0];
\n }
\n }

return $meta;\n

});
\n `

A more complete solution could look like that:

`php\n

add_filter( ‘jekyll_export_meta’, function($meta) {
\n foreach ($meta as $key => $value) {
\n // Advanced Custom Fields
\n if (is_array($value) && count($value) === 1 && array_key_exists(0, $value)) {
\n $value = maybe_unserialize($value[0]);
\n // Advanced Custom Fields: NextGEN Gallery Field add-on
\n if (is_array($value) && count($value) === 1 && array_key_exists(0, $value)) {
\n $value = $value[0];
\n }
\n }
\n // convert types
\n $value = match ($key) {
\n // Advanced Custom Fields: “true_false” type
\n ‘my-bool’ => (bool) $value,
\n default => $value
\n };
\n $meta[$key] = $value;
\n }

return $meta;\n

});
\n `

Removing Empty or Falsy Values

If you want to remove empty or falsy values from the frontmatter (similar to the pre-3.0.3 behavior), you can use the jekyll_export_post_meta filter:

`php\n

add_filter( ‘jekyll_export_post_meta’, function( $meta, $post ) {
\n foreach ( $meta as $key => $value ) {
\n // Remove falsy values except numeric 0
\n if ( ! is_numeric( $value ) && ! $value ) {
\n unset( $meta[ $key ] );
\n }
\n }
\n return $meta;
\n}, 10, 2 );
\n `

Command-line Usage

If you’re having trouble with your web server timing out before the export is complete, or if you just like terminal better, you may enjoy the command-line tool.

It works just like the plugin, but produces the zipfile on STDOUT:

`\n

php jekyll-export-cli.php > jekyll-export.zip
\n `

If using this method, you must run first cd into the wordpress-to-jekyll-exporter directory.

Alternatively, if you have WP-CLI installed, you can run:

`\n

wp jekyll-export > export.zip
\n `

The WP-CLI version will provide greater compatibility for alternate WordPress environments, such as when wp-content isn’t in the usual location.

Filtering by Category or Tag

You can export only specific categories or tags using the WP-CLI command. This is useful when you want to convert just one section of your WordPress site instead of the entire corpus.

Export posts from a specific category:

`bash\n

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

Export posts from multiple categories:

`bash\n

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

Export posts with a specific tag:

`bash\n

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

Export only pages (or specific post types):

`bash\n

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

Combine filters:

`bash\n

wp jekyll-export –category=technology –tag=featured –post_type=post > export.zip
\n

`Using Filters in PHP`


\nIf you're using the plugin via PHP code or want more control, you can use the

jekyll_export_taxonomy_filters` filter:

`php\n

add_filter( ‘jekyll_export_taxonomy_filters’, function() {
\n return array(
\n ‘category’ => array( ‘technology’, ‘science’ ),
\n ‘post_tag’ => array( ‘featured’ ),
\n );
\n} );

// Then trigger the export
\nglobal $jekyll_export;
\n$jekyll_export->export();
\n `

Test Coverage Improvements

Overview

This document summarizes the comprehensive testing improvements made to the WordPress to Jekyll Exporter plugin.

Test Files Added

1. `tests/test-cli.php` – CLI Command Tests

Tests for the WP-CLI integration functionality:
\n– Verifies Jekyll_Export_Command class exists when WP_CLI is defined
\n– Tests that the command has the required __invoke method
\n– Validates command instantiation

2. `tests/test-integration.php` – Integration Tests

Comprehensive integration tests for the full export workflow:
\n– Full export workflow validation (config + posts + uploads)
\n– Zip file creation and contents verification
\n– Multi-post type handling (posts, pages, drafts)
\n– Upload file copying and export
\n– Special character handling in titles
\n– End-to-end YAML front matter validation
\n– Markdown conversion validation

3. `tests/test-edge-cases.php` – Edge Case Tests

Tests for edge cases and error conditions:
\n– Posts with very long titles
\n– Unicode characters (émojis, 中文, العربية)
\n– HTML in post titles
\n– Table conversion to Markdown
\n– Shortcode processing
\n– Serialized post meta data
\n– Empty post slugs
\n– Post formats
\n– Serialized options
\n– Symbolic links
\n– Empty post lists
\n– Invalid dates

Enhanced Tests in `test-wordpress-to-jekyll-exporter.php`

Added comprehensive tests for previously untested or under-tested functions:

New Function Tests

test_filesystem_method_filter() – Verifies the filesystem method filter returns ‘direct’
test_register_menu() – Tests menu registration in WordPress admin
test_zip_folder_empty() – Tests zip creation with empty directories
test_zip_folder_nested() – Tests zip creation with nested directory structures

New Edge Case Tests

test_convert_meta_no_custom_fields() – Tests meta conversion without custom fields
test_convert_meta_with_featured_image() – Tests featured image handling in meta
test_convert_terms_no_terms() – Tests term conversion when no terms exist
test_convert_content_empty() – Tests conversion of empty content
test_convert_content_complex_html() – Tests conversion of complex HTML (headings, links, lists)
test_write_draft() – Tests writing draft posts to _drafts directory
test_write_future() – Tests writing future posts to _posts directory
test_write_subpage() – Tests writing sub-pages with correct paths
test_rename_key_nonexistent() – Tests rename_key with non-existent keys
test_convert_options_filters_hidden() – Tests that hidden options are filtered
test_get_posts_caching() – Tests post caching mechanism
test_copy_recursive_skips_temp() – Tests that temporary directories are skipped

Test Coverage Summary

Previously Tested Functions

✅ Plugin activation
✅ Dependency loading
✅ Getting post IDs
✅ Converting meta (basic)
✅ Converting terms (basic)
✅ Converting content (basic)
✅ Temp directory initialization
✅ Converting posts
✅ Exporting options
✅ Writing files
✅ Creating zip
✅ Cleanup
✅ Rename key
✅ Converting uploads
✅ Copy recursive (basic)

Newly Added Test Coverage

✅ CLI command functionality
✅ Filesystem method filter
✅ Menu registration
✅ Featured images in meta
✅ Complex HTML to Markdown conversion
✅ Draft and future post handling
✅ Sub-page path handling
✅ Empty and edge case content
✅ Hidden option filtering
✅ Post caching
✅ Temporary directory exclusion
✅ Full export workflow integration
✅ Zip contents validation
✅ Multi-post type exports
✅ Unicode character handling
✅ HTML in titles
✅ Table conversion
✅ Shortcode processing
✅ Serialized data handling
✅ Symbolic link handling
✅ Long titles
✅ Post formats
✅ Special characters

Coverage Statistics

Original Test File

Lines: 415
Test Functions: 15

Enhanced Test Files

test-wordpress-to-jekyll-exporter.php: 699 lines (+284), 31 test functions (+16)
test-cli.php: 60 lines (new), 3 test functions (new)
test-integration.php: 247 lines (new), 6 test functions (new)
test-edge-cases.php: 273 lines (new), 15 test functions (new)

= Total …

\n","downloaded":43331,"faq":null,"homepage":"https://github.com/benbalter/wordpress-to-jekyll-exporter/","icons":[{"type":"1x","url":"https://ps.w.org/jekyll-exporter/assets/icon-128x128.png?rev=3073421"},{"type":"2x","url":"https://ps.w.org/jekyll-exporter/assets/icon-256x256.png?rev=3073421"}],"installation":null,"internal_ranking":0,"languages":[],"last_seen":{"timestamp":1781816041.504,"timezone":"UTC"},"last_updated":{"timestamp":1777586280,"timezone":"UTC"},"last_wordpress_compatible_version":"6.9.4","latest_num_ratings":9,"latest_rating":3.2,"latest_ratings":{"1":3,"2":1,"3":0,"4":1,"5":4,"links":{"1":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=1","alt":"View all 3 one star reviews"},"2":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=2","alt":"View all 1 two star reviews"},"3":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=3","alt":"View all 0 three star reviews"},"4":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=4","alt":"View all 1 four star reviews"},"5":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=5","alt":"View all 4 five star reviews"},"all":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/","alt":"View all 9 reviews"}}},"minimum_php_version":"8.2","minimum_wordpress_version":"6.4","name":"Static Site Exporter","num_ratings":12,"pluginid":"jekyll-exporter","rating":3.5,"ratings":{"1":3,"2":1,"3":1,"4":1,"5":6,"links":{"1":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=1","alt":"View all 3 one star reviews"},"2":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=2","alt":"View all 1 two star reviews"},"3":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=3","alt":"View all 1 three star reviews"},"4":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=4","alt":"View all 1 four star reviews"},"5":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/?filter=5","alt":"View all 6 five star reviews"},"all":{"url":"https://wordpress.org/support/plugin/jekyll-exporter/reviews/","alt":"View all 12 reviews"}}},"reviews":[],"screenshots":null,"short_description":"Features","support_threads":0,"support_threads_resolved":0,"tags":[{"slug":"export","label":"export","count":386},{"slug":"github","label":"Github","count":115},{"slug":"yaml","label":"yaml","count":6},{"slug":"jekyll","label":"jekyll","count":2},{"slug":"github-pages","label":"github pages","count":1}],"tags_count":510,"languages_count":0,"age_days":4220.934468020012,"installs_per_rating":41.666666666666664,"downloads_per_rating":3610.9166666666665,"installs_per_day":0.11845718141048132,"downloads_per_day":10.265736255395133,"reviews_per_day":0.002842972353851552,"activation_rate":0.011539082873693199,"version":"4.0.4","marketplace":"wordpress","marketplace_url":"https://wordpress.org/plugins/jekyll-exporter","price":null,"wordpress_link":{"alt":"WordPress","url":"https://wordpress.org/plugins/jekyll-exporter"}}

Alternatives to Static Site Exporter

Top alternatives