Markdown for agents

Every public page here is published twice: once as HTML for people, once as Markdown for agents. The Markdown is not a summary or a rendering of the page — it is the same content, written for something that reads text rather than pixels.

Two families are deliberately outside this: component previews, which exist to be rendered rather than read, and paginated blog pages after the first, which the blog twin already lists in full. An index twin is an exhaustive listing rather than a copy of the HTML page, so it carries no filter or pagination state.

Append .md to any path #

The home page's twin is /index.md: /.md would be a legal URL but an unreadable one. Every twin is served as text/markdown; charset=utf-8, carries X-Content-Type-Options: nosniff, and carries a Link: <page>; rel="canonical" header naming the HTML page as the preferred URL for the pair:

GET /prompts/design-token-system.md

200 OK
Content-Type: text/markdown; charset=utf-8
Link: <https://pagesugar.com/prompts/design-token-system>; rel="canonical"
X-Content-Type-Options: nosniff

Twins are rendered per request rather than published as static files, which is what keeps those headers: a static file on the CDN carries only the content type its extension implies. They are cached at the edge all the same, so the cost is one render per cache miss rather than one per request.

Each HTML page also advertises its twin in the head:

<link rel="alternate" type="text/markdown" href="/docs/markdown-for-agents.md" />

A component's Markdown contains its source #

https://pagesugar.com/components/<slug>.md is the one that matters most. Alongside the identity, props, palette tokens, dependencies, accessibility notes and licence, it inlines every exported text file of the component, fenced and labelled by path, byte for byte:

## Source

- Palette: Slate (`slate`)
- Entry: `PricingGrid.svelte`
- Suggested directory: `src/lib/components/pricing`

#### `PricingGrid.svelte`

Role: component · 7421 bytes · SHA-256 `…`

```svelte
<script lang="ts">
  …
</script>
```

One request gives an agent the whole component. There is no second round trip to fetch files, and nothing to unzip.

Three query parameters narrow it, all optional:

• ?variant=<id> — inline that palette instead of the default.
• ?version=<v> — pin a release rather than taking the current one.
• ?source=links — metadata only, with the files linked rather than inlined. Useful when you are comparing components and do not want the code yet.

A binary file, or one past the inline size ceiling, is named in place with its size, hash and a download URL rather than being inlined — the document never truncates silently. "Byte for byte" means the exported bytes: the compiler normalises every exported text file to end in a single newline, and it is those bytes, hashed and inlined, that the twin reproduces.

A prompt's Markdown is the prompt #

https://pagesugar.com/prompts/<slug>.md is the exception to "the same content, written for something that reads text": it carries no front matter, no title and no filing details — just the prompt body, exactly as it is meant to be pasted into an agent. The HTML page shows those same characters in a viewer rather than rendering them, and both read the same function, so what is read and what the Copy button puts on the clipboard cannot differ. The URL adds one terminating newline, as a text file should end with one.

https://pagesugar.com/prompts.md is the index: every prompt on its shelf, with the agents it is known to run on and anything it needs in place first. The bodies are linked rather than inlined there, and in llms-full.txt too. That is deliberate. A prompt is an instruction written to be handed to an agent, and a reference file that inlined all of them would hand an agent several sets of instructions it was never asked to follow. Fetch the one you want.

Start from llms.txt #

https://pagesugar.com/llms.txt follows the llms.txt convention: a short, structured index written for a model rather than a crawler. It names the integration contracts, the MCP endpoint, every published prompt and every published component. Most of its links are Markdown documents; a few point at the surfaces that have no Markdown form, such as the MCP endpoint itself and the JSON category listing.

https://pagesugar.com/llms-full.txt inlines every documentation page into a single file. Component source is deliberately left out of it and linked instead: the catalogue keeps growing, and a file large enough to hold all of it would be truncated by the context window of the agent reading it.

Content negotiation #

A client that sends an Accept header naming text/markdown above text/html is redirected to the twin:

GET /components/pricing-grid-01
Accept: text/markdown, text/html;q=0.9

303 See Other
Location: /components/pricing-grid-01.md

Negotiation is on Accept alone. This site does not inspect User-Agent to decide what a page says — serving different content to a named bot is cloaking, and it would misidentify the coding agents that matter, several of which send no distinguishing agent string at all.

Negotiation runs in two places, because pages differ in how they are served. Pages rendered per request are negotiated by the application, which parses the quality values in Accept and redirects only when Markdown genuinely outranks HTML. Pages served as static files from the CDN are negotiated by a routing rule instead, which can only pattern-match the header: it redirects when Accept names text/markdown and does not immediately weight it q=0. A client that names Markdown but ranks it below HTML is therefore sent to the twin by the CDN and kept on the HTML page by the application. The two also differ in status code — 303 from the application, 307 from the CDN.

Treat negotiation as a convenience. The .md URL is the contract, and it is always correct.

Which one should an agent use? #

• Retrieving a component to install it: the MCP server, or /components/<slug>.md. Both give you versioned source.
• Reading the documentation: /llms-full.txt in one request, or the individual .md twins.
• Running a design prompt: /prompts.md to choose one, then that prompt's own .md to get its text.
• Browsing or filtering the catalogue: the API, which returns JSON with cursors and filters. Markdown is for reading, not for querying.

Nothing you retrieve through any of these routes calls back to this site, and none of them can modify your project.