--- title: "The .md version of a post returns 404 or serves HTML" url: https://hostmy.blog/docs/rankready/markdown-url-404/ date: 2026-08-25 modified: 2026-08-25 lang: en author: "Aditya Sharma" description: "Fix a post's .md URL that 404s or serves HTML: enable Markdown in AI Visibility, re-save Permalinks to flush rewrites, and purge any stale cache." word_count: 671 --- # The .md version of a post returns 404 or serves HTML ## Start here If you added `.md` to a post URL and got a 404 or the normal HTML page, the usual reason is that the Markdown endpoint is switched off, or the rewrite rules have not been refreshed since you turned it on. Open **RankReady, AI Visibility, Markdown** and confirm the feature is enabled, then go to **Settings, Permalinks** and click Save. That single click flushes the rules and fixes most cases. ## Confirm Markdown is enabled RankReady only serves `/{post-slug}.md` and `/index.md` when the Markdown feature is on. Go to **RankReady, AI Visibility** and open the **Markdown** sub-tab. If the toggle is off, every `.md` URL returns a 404 because no handler is registered for it. Turn it on and save. If you skipped the [setup wizard](https://hostmy.blog/docs/rankready/rankready-setup-guide/) or unticked Markdown during it, this is the first thing to check. ## Flush the rewrite rules Turning Markdown on adds new rewrite rules, and WordPress does not always register them straight away. The fix is a rewrite flush: - Go to **Settings, Permalinks**. - Click **Save Changes**. You do not need to change anything, the save alone flushes the rules. - Reload your `.md` URL. Do this through the browser, on a normal page load. Flushing from WP-CLI or an MCP call inside the same request often does nothing, because the rewrite system already ran earlier in that request with the old value. A second, ordinary request is what makes the flush stick. RankReady 1.3.0 also self-heals a missing Markdown rule on the next admin page load and adds a raw request-path fallback, so on that version a fresh visit to wp-admin frequently clears the problem on its own. ## Clear a stale cache or CDN copy If the `.md` URL returns the full HTML page rather than Markdown, a cache or CDN is almost always serving an old copy that was captured before Markdown was enabled. RankReady marks its dynamic endpoints to bypass caching, but a layer that was already holding a response for that path will keep returning it until you purge. - Purge your page cache plugin, then purge the CDN or edge cache in front of it. - On Cloudflare, purge the URL and confirm no cache rule is storing it. - Reload and check again. See *Using RankReady with WP Rocket, LiteSpeed and Cloudflare* for the per-host purge steps and the bypass rules that keep these endpoints dynamic. ## Check the post itself A `.md` URL only resolves for content that RankReady will serve as Markdown. - **The post must be public and published.** Drafts, pending, private and password-protected posts will not return Markdown at a public `.md` address. - **The post type must be one Markdown is enabled for.** If you are testing a post type that is not covered, the `.md` URL will 404. Custom post type coverage is a Coming Soon feature and is not serving yet. ## Make sure the slug actually exists A hand-typed slug that does not match a real post gives a genuine 404, and that is correct behaviour, not a bug. Do not guess URLs. Pull real ones from your own index: open `/llms.txt` on your site, copy a listed post URL, and append `.md` to it. That guarantees you are testing a path RankReady knows about. ## Verify the fix Once you have made a change, fetch the URL and read the first lines. A working Markdown response starts with a YAML frontmatter block between `---` fences, followed by the post content as plain Markdown. `curl -s https://yoursite.com/your-post.md | head` If the first line is `---` and you can see fields such as the title and URL, the endpoint is serving correctly. If you still see `` or an HTML tag, a cache is still in the way, so purge again. Note that the distinct `.md` URL always returns Markdown regardless of the `Accept` header, by design, so you do not need to send any special header to test it. Content negotiation on the Accept header applies only to the canonical URL, which is covered in *[Accept: text/markdown](https://hostmy.blog/docs/rankready/accept-markdown-negotiation/) content negotiation explained*.