---
name: markdown-first-site
description: Build websites fully accessible through markdown: .md twins, llms.txt indexes, agenticweb.md, agents_md maintenance loops.
---

# Markdown-First Site

Every page has a markdown twin — the llms.txt discipline

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.