A WordPress plugin that serves a public post as Markdown when the request's Accept header prefers text/markdown. Everything else gets the normal HTML page.
$ curl -H 'Accept: text/markdown' https://example.com/hello-world/
# Hello world!
Welcome to WordPress. This is your first post.It is built for AI agents, LLM tooling and scripts that want a post's content without parsing a theme's HTML. It is deliberately small: one PHP file, no settings, no tables, no new URLs.
- Requirements
- Installation
- How it works
- What gets served
- Content negotiation
- Rendering
- Response headers
- Configuration for developers
- Security model
- Caching
- Known trade-offs
- What it does not do
- Development
- PHP 8.4 or later, with the
domandxmlextensions - WordPress 7.1.3 or later
- An HTTP cache in front of the site that honours
Vary, or none. Seravo's Nginx cache does. See Caching.
WordPress refuses to activate the plugin on older versions, based on the plugin header.
Copy accept-markdown.php, readme.txt and vendor_prefixed/ into wp-content/plugins/accept-markdown/ and activate the plugin. There is nothing to configure.
The plugin is not in the WordPress.org plugin directory, but it updates through the normal WordPress updater: the Update URI header makes WordPress ask the plugin instead of the directory, and the plugin checks the latest GitHub release twice a day. Only a release zip from this repository is ever offered; the package URL is built from the tag name and must match one of the release's assets. The "View details" window shows the release notes.
Posts and pages are served as Markdown straight away. Custom post types are not, until they opt in (see Post types).
To check it works:
curl -s -D - -H 'Accept: text/markdown' https://example.com/any-published-post/The response should have Content-Type: text/markdown and start with # and the post title.
The plugin registers seven hooks. Three of them do almost nothing on a normal request, two run only in the admin for plugin updates, one prints a discovery tag in the head, and the real work happens in template_redirect, after WordPress has resolved the URL to a post.
flowchart LR
A["plugins_loaded<br/>Markdown request? define DONOTCACHEPAGE"] --> B["init (priority 1)<br/>add support to post and page"]
B --> C["send_headers<br/>Vary: Accept on every front-end response"]
C --> D["template_redirect (last)<br/>Link header, then serve Markdown or do nothing"]
D --> W["wp_head<br/>alternate tag for an eligible post"]
U["update_plugins_github.com<br/>latest GitHub release, admin and cron only"] --> V["plugins_api<br/>the View details window"]
The handler runs at the last priority, so access gates that other plugins or the theme hook on template_redirect, such as login walls and maintenance modes, redirect or exit first.
On each front-end request, the handler decides between Markdown and doing nothing. "Do nothing" means WordPress carries on and renders the usual HTML page.
flowchart TD
R([Front-end request]) --> N{"Accept header<br/>prefers text/markdown?"}
N -- no --> H([Normal HTML page])
N -- yes --> E{"Hard checks pass?<br/>see What gets served"}
E -- no --> H
E -- yes --> S{"Post type supports accept-markdown<br/>and accept_markdown/allowed is true?"}
S -- no --> H
S -- yes --> U["Switch to a signed-out visitor"]
U --> M["Render and convert to Markdown<br/>apply accept_markdown/output"]
M --> X{"Anything thrown?"}
X -- yes --> H
X -- no --> O(["200 text/markdown<br/>with security headers"])
The hard checks always run first. Neither post type support nor the filter can override them.
A request gets Markdown only when every one of these is true:
| Check | Why |
|---|---|
Method is GET or HEAD |
Form posts and other methods behave as before |
| Not admin, REST, AJAX, cron or XML-RPC | The back end and APIs are never touched |
| Not a feed, preview, embed or trackback | Feeds, comment feeds, /embed/, /trackback/ and previews stay as they are |
| Status still 200, no headers sent | A gate that set 403 and lets the template show a message keeps its response |
| The main query is a single post, page or CPT entry | Archives, search and listings are out of scope |
Post status is exactly publish |
Drafts, pending, scheduled and private posts never leak, even to signed-in users |
| The post type is publicly viewable | Internal post types can never be exposed |
| The post has no password | Checked on the post itself, so a visitor who knows the password still gets HTML |
The post type supports accept-markdown |
Posts and pages by default; CPTs must opt in |
accept_markdown/allowed returns true |
Per-post decisions |
The Markdown is then rendered as a signed-out visitor. WordPress includes private posts in queries for signed-in users who can read them, so without this a Latest Posts or Query Loop block inside a public post could list private titles. Rendering signed out guarantees the Markdown only contains what an anonymous visitor could see.
The plugin compares how much the client wants text/markdown against text/html, following RFC 9110:
- For each of the two types, find the most specific matching entry: an exact match beats
text/*, which beats*/*. Among equally specific entries, the higher q-value wins. - Markdown is served only if its q-value is above 0 and higher than HTML's. A tie goes to Markdown when
text/markdownis named exactly, and to HTML when it only matches throughtext/*or*/*.
RFC 9110 says order does not express preference, so a strict reading would give text/markdown, text/html to HTML. In practice naming text/markdown at all is the preference: agents send that header, and browsers never name text/markdown. The exact-match condition keeps */* and text/* on HTML.
Matching is case-insensitive, whitespace around = is ignored, q-values are clamped to the range 0 to 1, and a non-numeric q counts as 0.
Accept header |
Result |
|---|---|
text/markdown |
Markdown |
TEXT/Markdown |
Markdown |
text/html;q=0.5, text/markdown;q=0.9 |
Markdown |
text/*;q=0.1, text/markdown |
Markdown |
text/html, text/markdown;q=0.5 |
HTML |
text/markdown, text/html |
Markdown (exact tie) |
text/markdown, text/html, */* |
Markdown (exact tie) |
text/*, text/html |
HTML (wildcard tie) |
text/markdown;q=0, */* |
HTML (Markdown refused) |
text/html;q=2, text/markdown |
Markdown (HTML's q clamped to 1, exact tie) |
A normal browser header, */* or text/* |
HTML |
No header, or application/json |
HTML, never a 406 |
A header longer than 4096 bytes or with more than 32 entries is treated as "not Markdown", so a crafted header cannot cost noticeable CPU.
Verified with 0.6.0 on a production Seravo site (2026-11-03), each header sent once with a cache-busting query string and once without, with the same result both ways:
| Client | Accept header |
Result |
|---|---|---|
| Claude Code fetch tool | text/markdown, text/html, */* |
Markdown |
| Cloudflare's documented client | text/markdown, text/html |
Markdown |
| Cursor | text/markdown;q=1.0, text/x-markdown;q=0.9, text/plain;q=0.8, text/html;q=0.7, */*;q=0.1 |
Markdown |
| Firefox | text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8 |
HTML |
| Generic client | */* |
HTML |
To check a site, loop over the headers and print the content type of each response:
for a in 'text/markdown, text/html' 'text/markdown, text/html, */*' '*/*' 'text/*'; do
printf '%-32s ' "$a"
curl -s -o /dev/null -w '%{content_type}\n' -H "Accept: $a" https://example.com/post/
doneThe content comes from the same the_content chain, in the main loop, that the signed-out HTML page uses. After that the plugin only removes things:
flowchart TD
P["Main loop, signed out"] --> S1
subgraph ISO["While the loop runs, restored afterwards"]
S1["1. the_content chain<br/>blocks, shortcodes and every plugin's filter, as on the page"]
I3["comment blocks render empty"]
I4["comment queries return nothing"]
end
S1 --> S4["2. Remove script, style, iframe, noscript,<br/>template, form, object, embed, svg<br/>with everything inside them"]
S4 --> S5["3. wp_kses_post<br/>drops javascript: links and disallowed markup"]
S5 --> S6["4. Flatten pre blocks, fix figure and figcaption"]
S6 --> S7["5. Convert to Markdown<br/>HTML comments and block delimiters dropped"]
S7 --> T["# Title + body"]
Notes on the chain:
- Why the real chain. Membership and paywall plugins (Paid Memberships Pro, MemberPress, Restrict Content Pro, Members, WooCommerce Memberships) gate published posts by filtering
the_contentor rewriting the post object in the query results. Such a post is still published, viewable and unprotected, so only that chain knows it is gated. An earlier version rendered rawpost_contentthrough a private chain and served those posts in full. The rule now: the plugin removes from what the page renders and never reconstructs content. - Gates in the template layer do not run. The handler serves Markdown and exits on
template_redirect, so a gate ontemplate_include,get_header, inside a theme template file, or ontemplate_redirectregistered after this plugin at the same last priority never runs for a Markdown request. This is the same exposure core gives a published post through the REST API, feeds and oEmbed. Gates on the query, onthe_contentand ontemplate_redirectbefore the handler are honoured. - Nested blocks go through the same chain. A Query Loop with Post Content, a Post Excerpt or a Latest Posts excerpt calls
the_contentfor the posts it renders, so the same gates apply to them. - Shortcodes and third-party filters run, as on the page. Share buttons or related-post text can appear; see Known trade-offs.
- Step 2 runs before kses on purpose. kses deletes disallowed tags but keeps the text between them, which would put script source and CSS into the Markdown. Closed elements go innermost first, then one pass removes everything from the first unclosed opener to the end, so malformed markup fails closed and a run of unclosed openers costs one pass, not one per opener.
- Code blocks lose syntax-highlighter markup and become plain fenced code.
- Tables become Markdown pipe tables.
- Images inside figures are kept on their own line, followed by the caption.
- Adjacent links with nothing between them (phone, email and "read more" in a flex-layout card) get a space, since the page keeps them apart with CSS only.
- The title is entity-decoded, stripped of tags and collapsed to a single line, so it cannot inject extra Markdown structure.
- Comments (WordPress comments) are never queried or rendered: no comment text, authors, counts, forms or Latest Comments, even when the post contains comment blocks.
Output is # <title>, a blank line, then the body, with at most one blank line in a row.
The converter is league/html-to-markdown 5.1.4, bundled under the plugin-private AcceptMarkdown\Vendor namespace so another plugin shipping a different version cannot conflict with it.
A Markdown response is 200 with these headers:
| Header | Value | Purpose |
|---|---|---|
Content-Type |
text/markdown; charset=<blog charset> |
Lets clients decode it |
Vary |
Accept |
Caches key on the Accept header |
Cache-Control |
none, like the HTML page | The HTTP cache treats both representations the same |
X-Content-Type-Options |
nosniff |
Browsers never sniff it as HTML |
Content-Security-Policy |
default-src 'none'; sandbox |
Nothing in it can run, even if a browser renders it |
X-Robots-Tag |
noindex |
Search engines do not index a duplicate |
HEAD returns the same status and headers with no body.
Every response for an eligible post, HTML or Markdown, also carries a discovery header, so an agent can find the Markdown representation from a HEAD request without parsing the page:
Link: <https://example.com/hello-world/>; rel="alternate"; type="text/markdown"The HTML head carries the same alternate, next to the JSON and RSS ones WordPress already prints there:
<link rel="alternate" type="text/markdown" href="https://example.com/hello-world/" />Both are only sent when a Markdown request for that URL would actually get Markdown (published, viewable type, no password, post type support and the allow filter all pass), so the header never promises something a request would not get. Note that this means the accept_markdown/allowed filter runs on every singular front-end request, not only on Markdown ones.
Every other front-end response gets Vary: Accept added and is otherwise unchanged.
There are no settings. Behaviour is changed with standard WordPress calls and two filters.
Eligibility per post type is the post type support feature accept-markdown. The plugin adds it to post and page on init at priority 1.
Opt a custom post type in when registering it:
register_post_type('book', [
'public' => true,
'supports' => ['title', 'editor', 'accept-markdown'],
]);Or add it later:
add_action('init', fn () => add_post_type_support('book', 'accept-markdown'));Opt any type out, including post and page, at the default init priority or later:
add_action('init', fn () => remove_post_type_support('page', 'accept-markdown'));Support is necessary but not sufficient. A post type that declares support still has to pass every hard check, so a non-viewable CPT is never served.
Decides per post. Receives the default (true when the post type has support) and the post.
Two things to know when writing one: it runs for the real visitor, before the plugin signs out for rendering, so current_user_can() sees the signed-in user while the Markdown itself is rendered signed out; and it runs on every singular front-end request, not only Markdown ones, because the discovery header and tag use the same decision.
// Keep one post out of Markdown.
add_filter('accept_markdown/allowed', function (bool $allowed, WP_Post $post): bool {
return $post->post_name === 'internal-notes' ? false : $allowed;
}, 10, 2);It runs after the hard checks, so returning true cannot expose a draft, a private post or a password-protected post.
Changes the final Markdown string. Receives the Markdown and the post.
// Add a source line at the end.
add_filter('accept_markdown/output', function (string $markdown, WP_Post $post): string {
return $markdown . "\nSource: " . get_permalink($post) . "\n";
}, 10, 2);If the filter throws, the visitor gets the normal HTML page.
The guiding rule: the Markdown never exposes anything the public HTML page does not already expose.
- Only the
Acceptheader and the request method are read from the request. No query parameters, cookies or other headers. - The only outbound request is the update check to the GitHub API, during admin and cron update checks, never on front-end requests. Only the tag name and the release notes (escaped before display) are read from the response; the package URL is built from the tag under this repository and must match a release asset.
- Hard eligibility checks run before, and independently of, post type support and the filter.
- Rendering happens as a signed-out visitor, and the main query is run again signed out first, so gates that decide at query time see the same visitor as the content filters.
- Content comes from the same
the_contentchain, in the main loop, that the signed-out HTML page uses, so membership and paywall gates apply to the Markdown. - Rendered HTML passes through the same post kses rules WordPress uses for untrusted authors, even when the content was written by a user with
unfiltered_html. - Non-content elements are removed with their contents before conversion.
- HTML comments and block delimiters are dropped.
- Any exception during rendering, including from the output filter, falls back silently to the normal HTML response, with no error details in the body. Everything is decided before the first header is sent, and anything printed while rendering is discarded, so stray output cannot break the headers or reach the body.
- The plugin creates no options, tables, cron jobs, rewrite rules or admin screens. The one site transient (the cached update check,
accept_markdown_release) expires by itself, so there is nothing to clean up on uninstall.
The same URL serves two representations, and Vary: Accept is what keeps them apart:
- Every front-end response carries
Vary: Accept. A standards-compliant HTTP cache stores Markdown and HTML as separate variants of the URL and serves each to the clients that asked for it, so Markdown is cached exactly like the HTML page. The plugin sends noCache-Controlof its own. - On Markdown requests the plugin defines
DONOTCACHEPAGE, which WordPress page-cache plugins such as WP Super Cache respect. They key on the URL alone, so they must not store Markdown at all. Such a plugin can still answer a Markdown request with a cached HTML page, because it runs before this plugin loads.
On Seravo, the primary hosting target: the first Markdown request for a post hits PHP, every later one is served by Nginx until the page is purged, and browsers never see a Markdown variant. Verified on a production site, most recently with 0.6.0 (2026-11-03): repeated requests with text/markdown, text/html and text/markdown, text/html, */* were X-Proxy-Cache: HIT with text/markdown, interleaved */* requests were HIT with text/html, and no HTML variant cached before the upgrade was served to the tie headers.
The plugin supports only caches that honour Vary. A CDN or proxy that stores HTML and ignores Vary (Cloudflare with a cache-everything rule, Varnish or Nginx configured to ignore it) will store a Markdown body under the page URL and serve it to visitors. The plugin cannot tell from inside a request what the cache does with its headers, and such caches commonly ignore Cache-Control too, so there is no header it could send instead. Configure that cache to bypass or key on Accept, or do not use the plugin behind it.
To verify a cache, request the same URL twice as a browser and once as an agent, and compare the cache status header (X-Cache, X-Proxy-Cache or similar) and the content type:
curl -sI https://example.com/post/ | grep -i -E 'x-.*cache|content-type'
curl -sI -H 'Accept: text/markdown' https://example.com/post/ | grep -i -E 'x-.*cache|content-type'The browser request should turn into a cache hit on the second run and stay text/html. The agent request should report text/markdown, and on a Vary-honouring cache it too becomes a hit on repeat.
- Third-party
the_contentoutput appears. Share buttons, related posts and similar text from other plugins can end up in the Markdown. Everything they add already appears on the public page. The alternative, a private rendering chain, bypassed membership plugins' content gates, so this is a deliberate choice. Trim with theaccept_markdown/outputfilter if needed. - Dynamic blocks are kept. Latest Posts, Query Loops and similar blocks render as on the public page. Because rendering is signed out, they only show public content.
- Third-party
render_blockfilters run. Their output can reach the Markdown. That output already appears on the public HTML page. - Embeds render as on the page. An embed whose markup is only an iframe (for example YouTube) is removed with the iframe and leaves nothing. Embeds with a fallback blockquote keep their text and link.
- Caches that answer early can serve HTML to agents. A cache that serves from
advanced-cache.php, or a server-level cache that answers before PHP runs without keying onAccept, responds before plugins load, so a Markdown request can get a cached HTML page. The reverse never happens with a page-cache plugin, becauseDONOTCACHEPAGEkeeps Markdown out of it. See Caching. - A Markdown request whose rendering throws falls back to the signed-out version of the HTML page.
- No
.mdURLs,?format=markdownor any other new URL or rewrite rule. - No Markdown feeds, archives, category, tag, author, search or front-page listing output.
- No comments in any form.
- No 406 responses.
- No site-level discovery file, no
robots.txtentry and no RSS-style autodiscovery. TheLinkheader and the head tag described under Response headers are the only advertising. - No front matter or metadata (author, dates, taxonomies). Use
accept_markdown/outputif you need it. - No conversion cache, settings page, options or WP-CLI commands.
- No rate limiting; that belongs to the web server or CDN.
accept-markdown.php The whole plugin
readme.txt WordPress.org plugin readme
vendor_prefixed/ Prefixed converter (built, shipped)
composer.json, composer.lock Pinned dependencies and scripts
scoper.inc.php php-scoper config for the prefixed build
phpunit.xml Test suite config
phpcs.xml.dist Coding standard (composer lint)
tests/
Pest.php HTTP request helpers
*Test.php Black-box HTTP tests
fixtures.php Test content, run with wp eval-file
accept-markdown-test.php Test mu-plugin (CPTs, shortcode, filters)
compose.yml, htaccess Disposable WordPress in Docker for the suite
bin/test-site Starts or removes the Docker test site
.github/workflows/test.yml Runs the suite, composer audit and composer lint on PHP 8.4 and 8.5
bin/release Bumps the version, commits and tags a release
.github/workflows/release.yml Builds the zip and publishes the GitHub release on a v* tag
SPEC.md The specification
CLAUDE.md, docs/agents/ Instructions for coding agents (issue tracker, triage labels, domain docs)
For local development, symlink the repo into a site's wp-content/plugins/accept-markdown.
Only accept-markdown.php, readme.txt, LICENSE and vendor_prefixed/ belong in a release. vendor/ holds dev tools.
composer install
composer build # prefixes league/html-to-markdown into vendor_prefixed/
composer auditThe build is reproducible: running composer build twice gives identical output.
All tests are black-box HTTP requests against a running WordPress site. They assert only on status, headers and body, and never call plugin code directly.
flowchart LR
T["Pest tests"] -->|HTTP requests| W["WordPress site<br/>plugin + test mu-plugin + fixtures"]
W -->|status, headers, body| T
Security tests use marker strings: each piece of content that must never reach Markdown (a draft, a script, a shortcode's output, a private post's title) carries a unique marker, and the tests check it is absent. Markers use letters only, because Markdown escapes _ and would hide a leak from a plain string search.
Run them from a shell that can reach the site's database (for Local, the "Open site shell"):
export ACCEPT_MARKDOWN_TEST_PASSWORD=any-value
wp eval-file tests/fixtures.php # installs the test mu-plugin and creates or updates fixtures
composer testACCEPT_MARKDOWN_TEST_PASSWORD sets the password of the am-test-admin user that the signed-in tests use; any value works as long as both commands see the same one. ACCEPT_MARKDOWN_BASE_URL points the tests at a different site (default http://accept-markdown.local).
Without a Local site, bin/test-site starts a disposable WordPress from the official images (tests/compose.yml: WordPress with Apache, MariaDB and wp-cli), activates the plugin, installs the test mu-plugin and creates the fixtures:
export ACCEPT_MARKDOWN_TEST_PASSWORD=any-value
bin/test-site up
ACCEPT_MARKDOWN_BASE_URL=http://localhost:8080 composer test
bin/test-site down # removes the containers and the databaseACCEPT_MARKDOWN_TEST_PORT changes the port, ACCEPT_MARKDOWN_WORDPRESS_IMAGE and ACCEPT_MARKDOWN_CLI_IMAGE pick other image tags (default php8.4-apache and cli-php8.4). The repo is mounted read-only into the site's plugins folder, so edits are live. CI (.github/workflows/test.yml) runs exactly this on PHP 8.4 and 8.5, plus composer audit, on every push to main and every pull request.
The fixture file is idempotent. It finds content by slug, creates it when missing and updates it otherwise. It never deletes anything.
composer lint # PHPCS with WordPress Coding Standards
composer lint:fix # fixes formatting (phpcbf)phpcs.xml.dist applies WordPress formatting to all PHP, and WPCS's security, database, i18n and WordPress API rules to the plugin. The tests make HTTP requests, so only their formatting is checked. A deliberate exception carries phpcs:ignore <sniff> -- <reason> on its line. The naming sniffs (snake_case variables and functions) and a few other non-formatting rules are off for now.
Versions follow semver from the commit types: feat bumps minor, fix, docs and perf bump patch, a breaking change bumps major.
- Add a
= X.Y.Z =entry to the changelog inreadme.txt. It becomes the GitHub release notes. - Run
bin/release X.Y.Z. It checks that the tree is clean, onmainand thatvendor_prefixed/matchescomposer build, then sets the version in the plugin header andreadme.txt, commits and tagsvX.Y.Z. - Push:
git push origin main vX.Y.Z.
The tag triggers .github/workflows/release.yml, which verifies the version, zips accept-markdown.php, readme.txt, LICENSE and vendor_prefixed/ under an accept-markdown/ folder and publishes a GitHub release with the zip attached. Install it by uploading the zip in WordPress or unpacking it into wp-content/plugins/.
The test mu-plugin is for test sites only. It registers test post types and a shortcode, hooks both filters, adds a login wall for ?am_test=gated, a 403 for ?am_test=forbidden, a stray-output content filter and two membership-style content gates, and turns off canonical redirects.
MIT. See LICENSE. The bundled converter, league/html-to-markdown, is MIT as well (vendor_prefixed/LICENSE).