concept-image/wp-markdown

Generates and serves a Markdown version of any WordPress page (via a .md URL or the Accept: text/markdown header), with caching and automatic cache invalidation.

1.0.4 2026-07-31 11:32 UTC

Requires

• php: >=8.1
• league/html-to-markdown: ^5.1
• roots/acorn: >=4.3

MIT

• Mathieu

Published on Packagist.org on 2026-07-31 09:32 UTC

README

WP Markdown automatically generates and serves a Markdown version of any page on the site (homepage, posts, pages, custom post types, archives, taxonomies, search results, 404 pages, ...).

How it works

• A page is served as Markdown if its URL ends with .md (e.g. /my-page/.md), or if the request includes the Accept: text/markdown header.
• The generated document includes a front matter header containing title, description, url, lang, and last_updated, followed by the page content converted to Markdown.
• The main content is extracted from the HTML actually rendered by the theme (the same template seen by visitors), not just from post_content. This means it works even when a theme renders its content from custom fields (ACF, ...) instead of the block editor.
• Each page is cached (via the application's configured Laravel cache store): indefinitely for singular content and the homepage (automatically invalidated when content is saved or deleted, and by Yoast SEO if the plugin is active), and for 6 hours for archives, search results, and 404 pages (since they depend on too many pieces of content to invalidate precisely).
• Append ?markdown_refresh=1 to any URL to force regeneration of its cache.
• You can test how AI-ready is your URL at acceptmarkdown.com

No command is provided to pre-generate the cache: each page is generated and cached automatically on its first request (or after it has been modified).

Installation

You can install the package via Composer:

composer require concept-image/wp-markdown

Adapting content extraction for another theme

The package attempts, in order, several common XPath selectors to locate the main content of a page in the rendered HTML ([itemprop="mainContentOfPage"], <main>, [role="main"], #main, #content, .entry-content, .site-content, <article>). If a theme's markup does not match any of these selectors, they can be replaced using a filter in the theme or a mu-plugin:

add_filter('wp_markdown_main_content_xpath', function (array $queries) {
    return ['//*[@id="my-content-container"]', ...$queries];
});

Additional filters are available:

• wp_markdown_front_matter — modify or add fields to the front matter (receives and returns an associative array containing title, description, url, lang, and last_updated).

Dependencies

• PHP >= 8.1
• roots/acorn (Laravel cache & service container)
• league/html-to-markdown (HTML → Markdown conversion)
• Yoast SEO (optional): if active, its already-computed titles, descriptions, and canonical URLs are reused, and its indexables cache automatically triggers invalidation of the corresponding Markdown cache.

Changelog

Please refer to CHANGELOG for more information.

Contributing

Please refer to CONTRIBUTING for more information.

License

Please refer to LICENSE for more information.