# Markdown and JSON twins (/docs/agents/twins)

> Every docs page as Markdown at its address plus .md, and every record a page renders as JSON beside its render.

An agent reads text, not layout. Every page here has a twin an agent can fetch whole: Markdown for a docs page, JSON for a rendered one.

## Markdown for every docs page

Add `.md` to any docs address: [`/docs/start/quickstart`](https://next.mdxui.dev/docs/start/quickstart) is [`/docs/start/quickstart.md`](https://next.mdxui.dev/docs/start/quickstart.md). The twin holds what the page holds:

- every included example inlined, as the page shows it;
- every address written in full on this site's origin;
- a Section type preview as the address of the manifest that lists its frames;
- no MDX comments; a component stays as a tag around its content, so every step of a guide is in the text.

Copy Markdown and Open, under every page title, use the same twin.

## JSON for every rendered page

| You have | Its record |
| --- | --- |
| A worked-Site page, such as [`/sites/harbor/pricing`](https://next.mdxui.dev/sites/harbor/pricing) | [`/pages/harbor/pricing.json`](https://next.mdxui.dev/pages/harbor/pricing.json) |
| The landing, [`/`](https://next.mdxui.dev/) | [`/pages/home.json`](https://next.mdxui.dev/pages/home.json) |
| A whole worked Site | [`/sites/harbor/records.zip`](https://next.mdxui.dev/sites/harbor/records.zip) |
| A docs page that renders or cites a record | View as JSON, under its title |
| A Section type exemplar | Its `record` in [`/components/manifest.json`](https://next.mdxui.dev/components/manifest.json) |

A record is served byte for byte as the build renders it, so the JSON an agent copies parses.

## Why both

The Markdown says what to do; the JSON is what to change. An agent that reads the guide's twin and starts from the record's twin edits words in a structure that already parses, and fetches no HTML.