# One URL, two readers: serving the Jolts site as Markdown

What we found when we fetched every public Jolts page three ways, including a bug in our own audit.

Published: 2026-11-05T03:23:20Z

![One URL, two readers: serving the Jolts site as Markdown](https://jolts.xyz/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MTksInB1ciI6ImJsb2JfaWQifX0=--8f55a58a371f3ef3c394f0d88774c3a223555f6c/one-url-two-readers.webp)

Try opening our publisher page in a browser. Then ask for the same URL from a terminal:

```sh
curl -sS -H 'Accept: text/markdown' https://jolts.xyz/publishers | head
```

The first reader gets a page with a navigation bar, artwork and an interactive placement demo. The second gets a document it can read as text. We wanted someone evaluating Jolts from an agent or a shell to be able to follow the same trail as someone clicking through the website.

The blog already starts life as Markdown. Returning the stored article body is easy. The interesting case is a page like our publisher overview, where the copy lives in a Rails template alongside the interface. Maintaining a second document would mean remembering to edit two versions of the same product claim. Instead we render the template, remove interface elements such as forms and canvases, resolve relative links, and convert the result to Markdown.

## An audit that failed for the wrong reason

Our first production check flagged the About page. We had assumed a Markdown page would start with a heading. The founding letter opens with a short line introducing the authors, followed by its heading. Both readers had received the document we intended. The checker was enforcing a writing convention we had never asked the author to follow.

We changed the check to look for a top-level heading anywhere in the document. Then we ran it across the published sitemap before adding this article. **274 URLs, three representations apiece, 822 successful checks.** For each URL we fetched the HTML, followed its advertised Markdown alternate, and requested Markdown at the original URL. We checked the canonical link, description, Markdown heading, response type and cache variation. The count is a snapshot of our own site. It measures what our server returned on that run.

## Two headers worth looking at

Add `-D -` to the command above to print the response headers. The Link header names the canonical page and the explicit Markdown alternate. Vary includes Accept because a cache needs to distinguish a browser asking for HTML from a client asking for Markdown. A client that cannot set headers can follow the alternate directly.

You can inspect all three pieces yourself: [the publisher page as Markdown](https://jolts.xyz/publishers.md), [the sitemap we tested](https://jolts.xyz/sitemap.xml), and [our short index for agents](https://jolts.xyz/llms.txt).



## Next step

[Explore advertising](https://jolts.xyz/advertisers) or [monetize your AI app](https://jolts.xyz/publishers).