{"id":31827210,"url":"https://github.com/roots/post-content-to-markdown","last_synced_at":"2026-04-18T21:07:34.362Z","repository":{"id":317797458,"uuid":"1068879721","full_name":"roots/post-content-to-markdown","owner":"roots","description":"A WordPress plugin that converts post content to Markdown when requested with an `text/markdown` Accept header.","archived":false,"fork":false,"pushed_at":"2025-10-03T04:19:25.000Z","size":5,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-03T05:43:46.571Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"roots"}},"created_at":"2025-10-03T03:51:25.000Z","updated_at":"2025-10-03T04:22:31.000Z","dependencies_parsed_at":"2025-10-03T05:43:50.787Z","dependency_job_id":"1e4419e8-ab5a-43a5-b9a9-81cafa6d1000","html_url":"https://github.com/roots/post-content-to-markdown","commit_stats":null,"previous_names":["roots/post-content-to-markdown"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/roots/post-content-to-markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roots%2Fpost-content-to-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roots%2Fpost-content-to-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roots%2Fpost-content-to-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roots%2Fpost-content-to-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roots","download_url":"https://codeload.github.com/roots/post-content-to-markdown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roots%2Fpost-content-to-markdown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279008288,"owners_count":26084430,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T18:23:09.783Z","updated_at":"2026-04-18T21:07:34.346Z","avatar_url":"https://github.com/roots.png","language":"PHP","funding_links":["https://github.com/sponsors/roots"],"categories":[],"sub_categories":[],"readme":"# Post Content to Markdown\n\n[![Packagist Downloads](https://img.shields.io/packagist/dt/roots/post-content-to-markdown?label=downloads\u0026colorB=2b3072\u0026colorA=525ddc\u0026style=flat-square)](https://packagist.org/packages/roots/post-content-to-markdown)\n[![Follow Roots](https://img.shields.io/badge/follow%20@rootswp-1da1f2?logo=twitter\u0026logoColor=ffffff\u0026message=\u0026style=flat-square)](https://twitter.com/rootswp)\n[![Sponsor Roots](https://img.shields.io/badge/sponsor%20roots-525ddc?logo=github\u0026style=flat-square\u0026logoColor=ffffff\u0026message=)](https://github.com/sponsors/roots)\n\nA WordPress plugin that returns post content in Markdown format when requested with an `Accept` header set to `text/markdown`, a `.md` URL suffix (e.g. `/hello-world.md`), or a `?format=markdown` query parameter.\n\n| Query parameter / `.md` URL | Accept header |\n|-------------|---------------|\n| ![Screenshot of the plugin output on WP's default Hello World post](https://cdn.roots.io/app/uploads/post-content-to-markdown-hello-world.png?2) | ![Screenshot of the plugin output on WP's default Hello World post (Accept header)](https://cdn.roots.io/app/uploads/post-content-to-markdown-hello-world-curl.png) |\n\n## Support us\n\nRoots is an independent open source org, supported only by developers like you. Your sponsorship funds [WP Packages](https://wp-packages.org/) and the entire Roots ecosystem, and keeps them independent. Support us by purchasing [Radicle](https://roots.io/radicle/) or [sponsoring us on GitHub](https://github.com/sponsors/roots) — sponsors get access to our private Discord.\n\n## Requirements\n\nPHP 8.1+\n\n## Installation\n\n### via Composer\n\n```bash\ncomposer require roots/post-content-to-markdown\n```\n\n### Manual\n\n1. Download the [latest release](https://github.com/roots/post-content-to-markdown/releases)\n2. Place in `wp-content/plugins/post-content-to-markdown/`\n3. Activate via wp-admin or WP-CLI\n\n## Usage\n\n### Accept headers (ideal for LLMs)\n\nSend an `Accept: text/markdown` header to any of these URLs:\n\n- **Single post:** `https://example.com/post-slug/` → Returns post content as Markdown\n- **Single post with comments:** `https://example.com/post-slug/feed/` → Returns post + all comments\n- **Main feed:** `https://example.com/feed/` → Returns latest posts as Markdown\n\n**Examples:**\n\n```bash\n# Single post\ncurl -H \"Accept: text/markdown\" https://example.com/my-awesome-post/\n\n# Single post with comments\ncurl -H \"Accept: text/markdown\" https://example.com/my-awesome-post/feed/\n\n# Main feed\ncurl -H \"Accept: text/markdown\" https://example.com/feed/\n```\n\n### Query parameters (accessible/shareable)\n\nFor browsers and sharing, use the `?format=markdown` query parameter:\n\n- **Single post:** `https://example.com/post-slug/?format=markdown`\n- **Single post with comments:** `https://example.com/post-slug/feed/?format=markdown`\n- **Main feed:** `https://example.com/feed/?format=markdown`\n\n**Examples:**\n\n```bash\n# View in browser\nhttps://example.com/my-awesome-post/?format=markdown\n\n# Get post with comments\nhttps://example.com/my-awesome-post/feed/?format=markdown\n\n# Get main feed\nhttps://example.com/feed/?format=markdown\n```\n\n### `.md` URL suffix\n\nAppending `.md` to any permalink returns the same Markdown representation and is a first-class, shareable URL.\n\n```bash\n# Equivalent to Accept: text/markdown\ncurl https://example.com/my-awesome-post.md\n```\n\n`.md` URL responses include `X-Robots-Tag: noindex, nofollow` so search engines don't index the Markdown alias alongside the canonical HTML page. Disable this feature with the `post_content_to_markdown/md_url_enabled` filter.\n\nHTML responses advertise the Markdown representation two ways so both RFC 8288-aware crawlers and HTML-parsing clients can discover it without sending `Accept: text/markdown`:\n\n```\nLink: \u003chttps://example.com/my-awesome-post.md\u003e; rel=\"alternate\"; type=\"text/markdown\"\n```\n\n```html\n\u003clink rel=\"alternate\" type=\"text/markdown\" href=\"https://example.com/my-awesome-post.md\"\u003e\n```\n\n### Response headers\n\nMarkdown responses carry:\n\n- `Content-Type: text/markdown; charset=utf-8`\n- `Vary: Accept` — tells caches to key by `Accept` so the HTML and Markdown representations don't cross-serve.\n- `X-Markdown-Source: accept | md-url | query` — identifies how the client asked for Markdown. Useful for inspecting agent traffic in access logs.\n\n### Dedicated Markdown feed\n\nA dedicated Markdown feed is also available at `/feed/markdown/`:\n\n```bash\ncurl https://example.com/feed/markdown/\n```\n\nThe feed includes:\n- Feed metadata (site name, description, last updated, feed URL)\n- Post title, author, publication date (ISO 8601), and permalink\n- Post categories and tags\n- Post content converted to Markdown\n- Optional excerpt support\n- Optional comment support\n\n**Example Output:**\n\n```markdown\n# My WordPress Site - Markdown Feed\n\n**Description:** Just another WordPress site\n**Last Updated:** 2025-10-03T19:45:00+00:00\n**Feed URL:** https://example.com/feed/markdown/\n\n---\n\n# Hello World!\n\n**Author:** John Doe\n**Published:** 2025-10-03T12:00:00+00:00\n**URL:** https://example.com/hello-world/\n**Categories:** News, Updates\n**Tags:** announcement, wordpress\n\nWelcome to WordPress. This is your first post. Edit or delete it, then start writing!\n\n---\n```\n\n**Feed URL structure:**\n\nMarkdown feeds are accessible via:\n- `/feed/markdown/` - Dedicated Markdown feed\n- `/feed/?format=markdown` or `/feed/` with `Accept: text/markdown` - Main feed as Markdown\n- `/post-slug/feed/?format=markdown` or `/post-slug/feed/` with `Accept: text/markdown` - Single post with comments\n\nNote that WordPress requires pretty permalinks to be enabled (Settings → Permalinks must be set to anything other than \"Plain\").\n\n**Autodiscovery:**\n\nThe plugin automatically adds a `\u003catom:link\u003e` element to your site's RSS feed, allowing feed readers and LLMs to discover the Markdown version:\n\n```xml\n\u003catom:link href=\"https://example.com/feed/markdown/\" rel=\"alternate\" type=\"text/markdown\" /\u003e\n```\n\n## Filters\n\nThe plugin provides several filters for customization:\n\n### Single post filters\n\n#### `post_content_to_markdown/post_types`\n\nFilter the post types that can be served as Markdown for single posts.\n\n```php\nadd_filter('post_content_to_markdown/post_types', function ($post_types) {\n    // Add support for pages and custom post types\n    return ['post', 'page', 'product'];\n});\n```\n\n**Default:** `['post']`\n\n#### `post_content_to_markdown/post_allowed`\n\nFilter whether a specific post is allowed to be served as Markdown. Runs after the post type check, so it only receives posts whose type is already allowed. Returning `false` short-circuits the Markdown response and falls through to the normal HTML render.\n\n```php\nadd_filter('post_content_to_markdown/post_allowed', function ($allowed, $post) {\n    // Only serve Markdown for specific page slugs\n    if ($post-\u003epost_type === 'page') {\n        return in_array($post-\u003epost_name, ['example', 'example-2'], true);\n    }\n\n    return $allowed;\n}, 10, 2);\n```\n\nOr restrict by post ID:\n\n```php\nadd_filter('post_content_to_markdown/post_allowed', function ($allowed, $post) {\n    if ($post-\u003epost_type === 'page') {\n        return in_array($post-\u003eID, [1, 2, 3], true);\n    }\n\n    return $allowed;\n}, 10, 2);\n```\n\n**Default:** `true`\n\n#### `post_content_to_markdown/md_url_enabled`\n\nControls whether `.md` URL suffixes (e.g. `/about.md`) are treated as a Markdown request. Enabled by default so consumers get shareable Markdown URLs automatically. Disable if you'd rather only accept Markdown requests via the `Accept` header or `?format=markdown` query parameter.\n\n```php\nadd_filter('post_content_to_markdown/md_url_enabled', '__return_false');\n```\n\n**Default:** `true`\n\n#### `post_content_to_markdown/strict_accept`\n\nControls whether the plugin returns `406 Not Acceptable` when the client's `Accept` header rules out every representation the site can serve (i.e. neither `text/html` nor `text/markdown` is acceptable). Enabled by default for spec-correct content negotiation. Disable if you'd rather always fall back to HTML for any `Accept` value.\n\n```php\nadd_filter('post_content_to_markdown/strict_accept', '__return_false');\n```\n\n**Default:** `true`\n\n#### `post_content_to_markdown/emit_vary`\n\nControls whether the plugin appends `Vary: Accept` to every front-end response. Enabled by default so that downstream caches (browsers, proxies, CDNs) key on the Accept header and don't cross-serve an HTML response to a Markdown request (or vice versa). Disable if you don't want the plugin touching HTML response headers — Markdown responses will still include `Vary: Accept` regardless, so content negotiation stays correct for direct Markdown hits.\n\n```php\nadd_filter('post_content_to_markdown/emit_vary', '__return_false');\n```\n\n**Default:** `true`\n\n#### `post_content_to_markdown/cache_md_urls`\n\nBy default the plugin sets `DONOTCACHEPAGE` for every Markdown request so WordPress page caches (WP Super Cache, Batcache, etc.) don't cross-serve a Markdown body to an HTML client. `.md` URLs are a distinct URL key and safe to cache in principle, but WP page caches can transform response bodies assuming HTML (gzip, footer injection, cache-comment insertion), so caching them is opt-in. Enable if your page cache passes non-HTML bodies through untouched.\n\n```php\nadd_filter('post_content_to_markdown/cache_md_urls', '__return_true');\n```\n\n**Default:** `false`\n\n### Feed filters\n\n#### `post_content_to_markdown/feed_post_types`\n\nFilter the post types included in the Markdown feed.\n\n```php\nadd_filter('post_content_to_markdown/feed_post_types', function ($post_types) {\n    return ['post', 'page'];\n});\n```\n\n**Default:** `['post']`\n\n#### `post_content_to_markdown/feed_posts_per_page`\n\nFilter the number of posts included in the Markdown feed.\n\n```php\nadd_filter('post_content_to_markdown/feed_posts_per_page', function ($count) {\n    return 20;\n});\n```\n\n**Default:** `10`\n\n#### `post_content_to_markdown/feed_include_comments`\n\nEnable or disable comments in the Markdown feed.\n\n```php\nadd_filter('post_content_to_markdown/feed_include_comments', function () {\n    return true;\n});\n```\n\n**Default:** `false`\n\n#### `post_content_to_markdown/feed_include_excerpt`\n\nEnable or disable post excerpts in the Markdown feed.\n\n```php\nadd_filter('post_content_to_markdown/feed_include_excerpt', function () {\n    return true;\n});\n```\n\n**Default:** `false`\n\n#### `post_content_to_markdown/feed_cache_duration`\n\nFilter the cache duration for the Markdown feed in seconds.\n\n```php\nadd_filter('post_content_to_markdown/feed_cache_duration', function ($duration) {\n    return 2 * HOUR_IN_SECONDS; // Cache for 2 hours\n});\n```\n\n**Default:** `HOUR_IN_SECONDS` (1 hour)\n\n### Conversion filters\n\n#### `post_content_to_markdown/conversion_cache_duration`\n\nFilter the cache duration for the HTML → Markdown conversion result in seconds. The conversion is memoized per content hash in the object cache; shorten this TTL if your content renders dynamically (e.g. dynamic blocks, request-aware shortcodes) and you want fresher output.\n\n```php\nadd_filter('post_content_to_markdown/conversion_cache_duration', function ($duration) {\n    return 5 * MINUTE_IN_SECONDS;\n});\n```\n\n**Default:** `HOUR_IN_SECONDS` (1 hour)\n\n#### `post_content_to_markdown/converter_options`\n\nFilter the HTML to Markdown converter options.\n\n```php\nadd_filter('post_content_to_markdown/converter_options', function ($options) {\n    return [\n        'header_style' =\u003e 'setext',           // Use underline style for H1/H2\n        'strip_tags' =\u003e false,                // Keep HTML tags without markdown equivalents\n        'remove_nodes' =\u003e 'script style img', // Remove script, style, and img elements\n        'hard_break' =\u003e false,                // Convert \u003cbr\u003e to two spaces + newline\n    ];\n});\n```\n\n**Available options:**\n- `header_style`: `'atx'` (default) or `'setext'`\n- `strip_tags`: Remove HTML tags without Markdown equivalents (default: `true`)\n- `remove_nodes`: Space-separated list of DOM nodes to remove (default: `'script style'`)\n- `hard_break`: Convert `\u003cbr\u003e` to newlines (default: `true`)\n\n#### `post_content_to_markdown/markdown_output`\n\nFilter the final Markdown output after conversion.\n\n```php\nadd_filter('post_content_to_markdown/markdown_output', function ($markdown, $original_html) {\n    // Add a footer to all Markdown output\n    return $markdown . \"\\n\\n---\\nConverted from HTML to Markdown\";\n}, 10, 2);\n```\n\n**Parameters:**\n- `$markdown`: The converted Markdown text\n- `$original_html`: The original HTML content\n\n## Performance\n\nThe HTML → Markdown conversion is cached at the object-cache layer (`wp_cache_get` / `wp_cache_set`) keyed on a content hash. Sites with a persistent object cache like Redis or Memcached avoid re-running block rendering, shortcode expansion, and the `league/html-to-markdown` conversion on repeat hits. Cache entries expire after an hour (filterable via `post_content_to_markdown/conversion_cache_duration`); content changes produce a new hash and a fresh entry, so no explicit invalidation is needed.\n\nThe cache assumes that rendering the same post content produces the same output. If you use dynamic blocks or shortcodes whose output varies by request context (e.g. current user, current time, site option that changes mid-TTL), the first render is frozen for the TTL window. Shorten the TTL via the filter above for content where that matters. The `post_content_to_markdown/markdown_output` filter runs on every request (after the cache lookup), so per-request customization there works without fighting the cache.\n\nThe Markdown feed is cached for 1 hour by default via a transient. The cache is automatically cleared when:\n- A post is published or updated\n- A post is deleted\n- Comments are added, edited, or deleted (when comments are included in feed)\n\nYou can customize the cache duration using the `post_content_to_markdown/feed_cache_duration` filter.\n\n## CDN configuration\n\nMost WordPress sites don't cache HTML at the CDN (WordPress is dynamic by default), in which case `Vary: Accept` has no practical cost. If you do cache HTML at the edge, `Vary: Accept` will fragment cache entries per user-agent `Accept` string (Chrome, Safari, agent UAs all send different values). Normalize `Accept` at the edge to two buckets — \"wants Markdown\" and \"anything else\" — before it reaches origin, then cache each bucket separately. On Cloudflare, a Cache Rule with a custom cache key that includes a normalized `Accept` header handles this; Cloudflare's [Markdown for Agents](https://blog.cloudflare.com/markdown-for-agents/) feature automates the normalization on supported zones.\n\n## Resources\n\n* [Serving Markdown to AI Agents via Accept Headers](https://benword.com/serving-markdown-to-ai-agents-via-accept-headers)\n* [The `text/markdown` Media Type](https://www.rfc-editor.org/rfc/rfc7763.html)\n\n## Community\n\nKeep track of development and community news.\n\n- Join us on Discord by [sponsoring us on GitHub](https://github.com/sponsors/roots)\n- Join us on [Roots Discourse](https://discourse.roots.io/)\n- Follow [@rootswp on Twitter](https://twitter.com/rootswp)\n- Follow the [Roots Blog](https://roots.io/blog/)\n- Subscribe to the [Roots Newsletter](https://roots.io/subscribe/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froots%2Fpost-content-to-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froots%2Fpost-content-to-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froots%2Fpost-content-to-markdown/lists"}