System Markdown Alternate

FAQ

Why is nothing served at the .md URL?

By default no post type is enabled. Open Settings → Markdown Alternate and
tick at least one post type under Supported post types.

Which content does NOT get a .md version?

Anything the endpoint would not be able to serve honestly:

• content types not enabled in the settings page;
• drafts, pending and private content, and password-protected posts;
• media attachments (always excluded);
• posts with a non-standard post format — aside, status, quote, link,
  gallery, image, video, audio, chat. These are short snippets, usually
  untitled, with no editorial body worth serving as a document. Use the
  sysmda_markdown_excluded_post_formats filter to change that.

Markdown is also never served for URL variants of a post — its feed, its
oEmbed view, its trackback endpoint, paged comments and the sub-pages of a
post split with <!--nextpage--> — even with Accept: text/markdown. Only the
canonical permalink and its .md URL return Markdown.

What does the Markdown output look like?

Each .md response is a UTF-8 document with a YAML front-matter block (title,
URL, Markdown URL, published/modified dates, and — when available — author,
featured image, categories, tags and a description), followed by the # Title
heading and the post body converted to clean Markdown. The exact keys, their
order and the escaping rules are documented as a stable contract, with
conformance tests, in docs/output-format.md in the source repository.

Can I include my custom taxonomies?

Yes. Open Settings → Markdown Alternate → Markdown output and tick the ones
you want under Custom taxonomies: the front matter then carries a
taxonomies: block with their terms, sorted alphabetically. Categories and tags
already have their own keys and are not repeated.

Nothing is selected by default and nothing is ever added implicitly — a taxonomy
registered by a plugin you install later shows up in the list unticked, so it
cannot start publishing itself. Taxonomies used for editorial classification
only, with no public term archive (“publicly queryable” off), are labelled as
internal in the list: they are still selectable, but only on purpose. Developers
can curate the list further with the sysmda_front_matter_taxonomy_slugs filter.

How do I exclude part of a post from the Markdown?

Add one of the CSS classes no-md, md-exclude or exclude-from-markdown to a
block; the element (and its children) is removed from the Markdown output. You
can customize the list with the sysmda_markdown_excluded_classes filter.

Does it affect my SEO?

The .md responses are sent with X-Robots-Tag: noindex, follow and a
Link: rel=”canonical” header pointing back to the HTML version, so search
engines are told to prefer the original page.

How do I get the Markdown URL in a button or template?

Use the [sysmda_md_url] shortcode. If you run GenerateBlocks 2.x, the
{{sysmda_md_url}} Dynamic Tag is available automatically — use it in element
fields such as a Button URL. When the post has no .md, the tag resolves to an
empty value so GenerateBlocks can hide the element instead of leaving a broken
link.

How do I let readers download the .md instead of opening it?

Use the [sysmda_md_download] shortcode. It prints a link that saves the file:

[sysmda_md_download]
[sysmda_md_download text="Save the Markdown"]
[sysmda_md_download id="123"]

The link carries the HTML download attribute, which is what tells the browser
to save the file instead of displaying it. The file name comes from the post
slug. Nothing changes on the server side: the .md URL itself behaves exactly
as it always has, so opening it directly still shows whatever your browser
normally does with a Markdown file.

The shortcode outputs a plain link with a single sysmda-md-download class, and
the plugin loads no CSS and no JavaScript on your site for it. Any styling is
your theme’s job.

Like [sysmda_md_url], it outputs nothing when the post has no Markdown version,
so it can never produce a link to a 404.

Is the .md content cached?

Yes (default 24h). It uses a persistent object cache when one is available and
falls back to transients otherwise. The cache is regenerated automatically when
the post is edited, when the plugin is updated, or when you save the settings —
and also when something outside the post changes what the Markdown says: a
synced pattern, the featured image, the description, an ACF field, the author’s
display name, the permalink structure or the site address.

That is the cache inside WordPress. Caches outside it — your browser, a page
cache, Varnish, a CDN — are told
Cache-Control: public, max-age=0, must-revalidate: they may keep a copy, but
they must ask the site whether it is still current before serving it, and the
answer is a small 304 Not Modified when nothing changed. So a .md cannot
keep circulating after you edit the article, without depending on anyone
purging it — which matters, because page caches purge the article’s URL and do
not know its .md version exists. If your infrastructure has its own purge
mechanism and you would rather trade that guarantee for raw speed, the
sysmda_cache_control filter lets you set a real lifetime.

Can I customize the plugin from my own code?

Yes: the plugin is developer-extensible through WordPress filters — which
content is served, the HTTP headers, the caching, every stage of the conversion
pipeline, the front matter and /llms.txt can all be changed from a theme or a
site plugin. A few examples:

add_filter( 'sysmda_markdown_output', fn( $md, $post ) => $md . "\n---\nCustom footer.\n", 10, 2 );

add_filter( 'sysmda_markdown_excluded_classes', fn( $classes ) => array_merge( $classes, array( 'my-private-block' ) ) );

add_filter( 'sysmda_llms_txt_enriched', '__return_true' );

Every filter, with its default value, what changing it does and how much
compatibility it promises, is documented here:
Developer extension API.
Hooks are labelled Stable or Advanced: the Advanced ones are supported and
documented, but may still evolve while the plugin is pre-1.0. The Markdown
output format itself is a separate, stronger contract.

Content negotiation misbehaves behind LiteSpeed cache. What can I do?

Some LiteSpeed cache configurations key the page cache by URL only and ignore
Vary: Accept, so a cached representation can be served regardless of the
Accept header. The plugin already tells the cache not to store the negotiated
Markdown; if requests for Markdown on the permalink still receive cached HTML,
enable LiteSpeed cache compatibility in Settings → Markdown Alternate →
Advanced: it adds .htaccess rules that make Markdown-negotiating requests
bypass the LiteSpeed page cache (normal browser traffic stays cached; on other
servers the rules are inert). Then purge the LiteSpeed cache. The explicit
.md URLs are not affected and remain fully cacheable.

Not sure whether your host is affected? Whether a LiteSpeed server honours
Vary: Accept depends on the host and cannot be detected automatically, so if
in doubt simply enable the option: it is the safe choice, and on hosts that
already behave correctly the rules are just redundant. To test it yourself:
open a post in a normal browser first (so its HTML gets cached), then request
the same permalink with a Markdown Accept header, for example:

curl -A "Mozilla/5.0" -H "Accept: text/markdown" https://example.com/my-post/

If the response is HTML (often with an x-litespeed-cache: hit header) instead
of Markdown, your server ignores Vary: Accept and you need the option. The
browser-like -A value matters: a WAF/CDN may block non-browser user agents.

Does it work behind a CDN (Cloudflare, Fastly, Varnish)?

The .md URLs need nothing from you. The negotiated permalink depends on your
CDN, and the difference matters:

• the dedicated .md URLs are their own cache key — one URL, one
  representation, nothing to mix up. Any CDN may store them, and
  Cache-Control: public, max-age=0, must-revalidate means it must revalidate
  before reuse, which is a cheap 304 Not Modified when nothing changed. This
  route works everywhere, with no configuration;
• the negotiated permalink (Accept: text/markdown on the HTML page’s own
  URL) is sent no-store, so a Markdown response is never stored and can never
  be handed to a browser that asked for HTML. That closes the harmful direction,
  but it cannot fix the opposite one: if your CDN caches the HTML page by URL and
  ignores Vary: Accept, a later Markdown request is answered at the edge, PHP
  never runs, and the client simply gets HTML. Vary: Accept is sent on every
  negotiable response, which is all a cache that honours it needs.

So for the negotiated route one of these has to be true: your CDN honours
Vary: Accept, or you configure it to bypass the cache — or to vary its cache
key — for requests whose Accept mentions text/markdown. On LiteSpeed the
plugin ships that bypass for you: see the previous entry. If you are not sure
which case you are in, the three-request test below tells you in a few seconds.
And the .md URL keeps working regardless — it is what the rel="alternate"
link and /llms.txt advertise, so agents following either one are unaffected.

Two more things worth knowing. Some CDNs rewrite validators in transit — Cloudflare
turns a strong ETag into a weak one — which the plugin handles: incoming
validators are compared with the weak-comparison rules, so revalidation keeps
working either way. And if you would rather have the CDN really cache the .md
instead of revalidating it, set a lifetime with the sysmda_cache_control
filter, keeping in mind that nothing purges a .md when you edit the post.

How do I check my cache is not mixing HTML and Markdown?

Send three requests to the same permalink, in this order, and compare the
content-type of each:

curl -sI -A "Mozilla/5.0" -H "Accept: text/markdown" https://example.com/my-post/
curl -sI -A "Mozilla/5.0" -H "Accept: text/html" https://example.com/my-post/
curl -sI -A "Mozilla/5.0" -H "Accept: text/markdown" https://example.com/my-post/

The first and third must answer text/markdown, the second text/html. If the
second returns Markdown, or the third returns HTML, something in front of PHP is
serving one stored representation to everyone: look at the age, x-cache,
cf-cache-status or x-litespeed-cache headers to see which layer, and purge it
(on LiteSpeed, see the entry above).

To check revalidation on a .md URL, read its etag and send it back:

curl -sI -A "Mozilla/5.0" https://example.com/my-post.md
curl -sI -A "Mozilla/5.0" -H 'If-None-Match: W/"paste-the-etag-here"' https://example.com/my-post.md

The second request should answer 304 with no body. A 200 instead is usually
not the plugin: some stacks strip conditional headers from the request before PHP
ever sees them (observed with nginx configured to cache the location). It is a
missed optimisation, not a correctness problem — the response is still current.

As above, the browser-like -A value matters: a WAF/CDN may block non-browser
user agents outright, and a block page is easy to mistake for a plugin bug.