Markdown Endpoints: Your Community, in a Format That AI Agents Can Read

Every question asked and answered in your community builds something powerful: a massive, crowdsourced knowledge library. But today, web-browser users aren't your only readers. AI agents, LLMs, and search engines are actively scanning your site for answers.

That’s why we’re rolling out Markdown endpoints for Discourse. You can now serve your site’s content in pure Markdown - a simple, standardized text format that makes your community's knowledge instantly accessible and perfectly optimized for both software and people. 

The problem with HTML

Web browsers rely on HTML to render pages, using a mix of text, layout code, stylesheets, and scripts to display information visually. But AI agents only care about the core content. When an AI processes an HTML page, it must first strip away this structural overhead - a computationally expensive process that wastes tokens. Worse, parsing HTML is error-prone; if the agent strips too much or leaves too much behind, it compromises the final output's accuracy.

The problem with raw output

Discourse already has a .raw output, which gives the text that the author wrote. But .raw has problems too.

The raw text often contains Discourse-specific syntax, such as shortcodes for uploads, quotes, and polls, that AI agents can’t easily interpret. On top of that, the .raw format frequently struggles to properly render standard structural elements like images, lists, and tables, making it an unreliable source for clean data extraction.

What Markdown endpoints do

Markdown endpoints provide the ideal solution. By delivering clean, standardized Markdown, they offer the perfect middle ground between the messy syntax of raw text and the heavy overhead of HTML:

• Smaller than HTML. There's no layout code, so the agent gets only the content.
• Better than .raw. Discourse processes the special syntax first. Images, lists, tables, and formatting are correct.
• Easy to read. People can read Markdown too, not only software.

Which pages you can get as Markdown

Markdown endpoints are currently available for two primary page types:

• Topic Views: Displays an individual topic along with its complete thread of posts.
• Topic Lists: Displays aggregated feeds of topics, including Latest, New, Categories, and Tags.

To handle large directories seamlessly, paginated topic lists include functional "previous" and "next" Markdown links, allowing AI agents to crawl and index the entire list effortlessly. 

How to request Markdown

Add .md to the URL. For example, change this URL:

https://community.example.com/t/my-topic/123

to this URL:

https://community.example.com/t/my-topic/123.md

Send an Accept header.

Software can send the header Accept: text/markdown. Then Discourse sends Markdown and not HTML. The URL doesn't change. LLMs or agents likely don't need any configuration; they should already pass the Accept header.

Here's an example with curl:

curl -H "Accept: text/markdown" https://community.example.com/latest

Who Markdown endpoints are for

• AI Agents & LLMs: Automated tools can parse your community's content rapidly and accurately. By eliminating HTML overhead, agents use fewer tokens and generate higher-quality responses from clean, structured input.
• Developers: Building integrations for Discourse is now virtually frictionless. Developers no longer need to write complex parsers to strip HTML or translate raw syntax - they receive ready-to-use Markdown instantly.
• Community Owners: As user behavior shifts from traditional search engines to AI assistants, making your site machine-readable ensures your community’s knowledge remains accessible, relevant, and widely distributed.
• Support Teams: Companies leveraging AI for customer service can point their tools directly at their Discourse forums. The AI can seamlessly extract existing solutions written by staff and users to automatically resolve new customer inquiries.
• Members: Users can effortlessly export entire topics as clean text to store in personal knowledge bases or feed into their own AI workflows.

Where this came from

Many thanks to Ben Word for creating the original Discourse to Markdown plugin feature in Discourse core. Ben also wrote the Accept Markdown specification, which sets out how websites can serve Markdown to software that asks for it.

We moved the feature into core because we think every Discourse site should serve Markdown to AI tools by default.

If you use the Discourse to Markdown plugin

Disable and uninstall it. While the plugin runs, it replaces some of the core endpoints, so you won't get the core version.

If your site sits behind Cloudflare

Cloudflare offers its own HTML-to-Markdown conversion. If you turn it on, Cloudflare may catch requests that carry Accept: text/markdown before they reach your site, convert the HTML itself, and serve that instead of Discourse's Markdown. To check, request a topic with that header and compare what you get with Cloudflare's feature on and off. If the output matches, Cloudflare is passing Discourse's Markdown through.

How to turn it on or off

You don't need to do anything. We've enabled Markdown endpoints for every hosted site in Upcoming Changes. If you self-host, update Discourse to get them.

To check that they work, add .md to any topic URL on your site.

If you'd rather turn them off, go to your Admin panel, find the site setting enable_markdown_endpoints, and switch it off.

Try it today

Add .md to a topic URL on your site, and you'll see what an AI agent sees. Then tell us what you find on Meta.