System Markdown Alternate

FAQ.KG

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;
• posts rendered by an unsupported page builder — Elementor, Divi, WPBakery, Oxygen, Beaver Builder or Breakdance. Their content is stored outside post_content, or stored in it as the builder’s own layout shortcodes, so the Markdown would come out either empty or full of layout wrappers converted as prose. A 404 is the honest answer; use the sysmda_markdown_unsupported_builders filter if you would rather have the empty document. Bricks pages are supported and get a real .md, rendered through Bricks’ own API — see the next question.

That last rule is decided per post, from the builder’s own render mode. Activating a builder does not affect posts you did not build with it, and a post you switched back to the WordPress editor keeps its Markdown version even though the builder data is still stored. Nothing is read from the post content, so an article quoting [et_pb_section] in a code sample is not mistaken for a Divi page.

How does the Bricks `.md` work?

The .md is built by calling Bricks’ own \Bricks\Frontend::render_data() on the page’s stored element tree — the plugin never re-implements Bricks’ elements. The existing md-exclude CSS class already works on any Bricks element (set it in the element’s CSS Classes field); a new Excluded builder elements list under Settings → Markdown Alternate → Markdown output additionally strips Bricks chrome by default — forms, nav menus, share bars, tables of contents, breadcrumbs — the same way excluded CSS classes are stripped, and it only adds to that list, never replaces it. A page switched to Render with WordPress is served from post_content as usual, whether or not Bricks data is still stored on it.

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 the Markdown output format reference.

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 add Copy as Markdown actions for readers?

Use [sysmda_md_actions]. It renders a GitHub-style split button: the main action copies the complete Markdown document, while the dropdown offers Copy as Markdown, View as Markdown in a new tab and Download Markdown. Use [sysmda_md_actions id="123"] for a specific post.

The component renders only where the shortcode is placed. Its small stylesheet and dependency-free script are loaded only on pages that actually render it, including placements in templates, widgets and secondary loops. The menu opens aligned to the button and drops below it, moving to the opposite side or above only when the screen edge leaves no room.

Like the other shortcodes, it outputs nothing when the target post has no Markdown version.

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.