Markdown-First Site

Make a website fully accessible to agents and readers alike. On PageWeave every page can carry two bodies: HTML for humans, markdown for machines. The markdown body is served at the same URL with .md appended and via Accept: text/markdown.

The four layers

1. Markdown twins on every page

For template pages bound to data tables, the pattern is mechanical:

• HTML body: {{ row.content | markdownify }}
• Markdown body: {{ row.content }} (raw)

For literal pages, author both bodies — the markdown version is a clean transcription, not an afterthought. Strip nav chrome, keep headings and links.

2. llms.txt (the index)

Follow the spec strictly:

# Site name

> One-paragraph summary.

Optional detail paragraphs.

## Section

- [Page title](https://site/page.md): what it contains

## Optional

- [Secondary](https://site/other.md)

H1 → blockquote → prose → H2 file-lists. Link the .md URLs, not the HTML ones. Keep it small enough to fit a context window; depth lives behind links.

3. agenticweb.md

A capability index in YAML-flavored markdown: what the site offers, how to query it (public JSON APIs at /t/{table_id}), update cadence, contact paths.

4. agents_md (maintenance)

Private instructions for agents working ON the site: table-driven editing workflow, field conventions, the "prefer full-page overwrites over replace_all patches" class of gotchas, release discipline.

Content rules

• Write content as markdown FIRST, then design around it. If a thing can't be expressed in markdown, question whether it needs to exist.
• Tables store content; pages render it. Never hand-maintain the same text in two places.
• Fenced code blocks in content fields render as copyable blocks in HTML and stay literal in markdown — the artifact travels intact.
• Keep URLs stable; redirects are cheap but trust isn't.

Verification loop

1. curl -H "Accept: text/markdown" <url> returns clean markdown.
2. <url>.md returns identical content.
3. /llms.txt links resolve and every link target is markdown.
4. An agent given ONLY llms.txt can answer three real questions about the site.