---
title: "Markdown content negotiation · Sitebulb Labs"
description: "Serving a Markdown version when an agent sends Accept: text/markdown makes your content cheaper and cleaner for it to read."
url: https://labs.sitebulb.com/docs/checks/content-accessibility/markdown-negotiation/
---

# Markdown content negotiation

Serving a Markdown version when an agent sends Accept: text/markdown makes your content cheaper and cleaner for it to read.

- Category

  [Content accessibility](https://labs.sitebulb.com/docs/checks/content-accessibility)

- Standard

  Recommended

## What it checks

The extension requests the page being scanned (not the homepage) with the `Accept` header a real agent sends:

```txt
Accept: text/markdown, text/html;q=0.9, */*;q=0.8
```

It passes when the response is successful, has a `text/markdown` (or `text/x-markdown`) content type, and the body does not start like an HTML document. An error page labelled as Markdown does not count.

If that fails, the extension tries two fallbacks so it can tell you what is close to working:

- A Markdown-looking body served as `text/plain`, which differs from what the same URL returns for `Accept: text/html`.
- Markdown served only when the request sends a bare `Accept: text/markdown`, which no real client sends.

This is the heaviest check in Content accessibility. The `.md` URL and `rel="alternate"` routes to Markdown are separate checks: [Markdown URL fallback](https://labs.sitebulb.com/docs/checks/content-accessibility/markdown-url-fallback) and [Markdown alternate link](https://labs.sitebulb.com/docs/checks/content-accessibility/markdown-link-alternate).

## Results

| Status   | When                                                                                   |
| -------- | -------------------------------------------------------------------------------------- |
| **Pass** | The realistic `Accept` header gets a successful `text/markdown` response               |
| **Warn** | A Markdown body is returned, but labelled `text/plain`                                 |
| **Warn** | Markdown is returned only for a bare `Accept: text/markdown`, not the realistic header |
| **Fail** | No Markdown version is offered through content negotiation                             |

## How to fix

When a request’s `Accept` header prefers `text/markdown`, respond with a Markdown version of the page and `Content-Type: text/markdown`. Parse the header properly, including quality values, rather than matching the exact string `text/markdown`.

Also send `Vary: Accept`, so caches keep the HTML and Markdown responses apart (see [Markdown negotiation caching](https://labs.sitebulb.com/docs/checks/content-accessibility/markdown-negotiation-vary)).

To test it:

```sh
curl -sI -H 'Accept: text/markdown, text/html;q=0.9, */*;q=0.8' https://example.com/page
```

The response should include `Content-Type: text/markdown`.