---
title: "What is sitemap.md? (and how to add one)"
description: "sitemap.md is a markdown index of your site's most important pages — the human- and agent-readable twin of sitemap.xml. What it is, where to serve it, how to structure it, and how to generate one."
last_updated: 2026-06-12
canonical_url: https://agent-ready.dev/what-is-sitemap-md
---

# What is sitemap.md? (and how to add one)

> sitemap.md is a markdown index of your site's most important pages — the human- and agent-readable twin of sitemap.xml.

**sitemap.md** is a markdown file that gives AI agents and humans a curated, structured overview of your site's most important pages — H2 sections grouping descriptive markdown links. Where sitemap.xml is a flat XML list built for crawlers, sitemap.md is something an agent can read and cite directly, and a person can browse. Most sites have the former and not the latter — which is why "no sitemap.md" is one of the [most common agent-readability mistakes](https://agent-ready.dev/common-agent-readability-mistakes).

## sitemap.md vs sitemap.xml

Complementary, not competing — ship both.

| | sitemap.xml | sitemap.md |
| --- | --- | --- |
| Format | XML | Markdown |
| Reader | Search-engine crawlers | AI agents & humans |
| Scope | Every indexable URL | Curated, high-value pages |
| Structure | Flat list + lastmod | H2 sections + described links |
| Since | 2005 | The agent era |

## Where do you put a sitemap.md?

Serve it at `/sitemap.md` (preferred). `/docs/sitemap.md` and `/.well-known/sitemap.md` are also recognised. A predictable, well-known path lets an agent find the file without being told where to look.

## What should a sitemap.md contain?

An H1 title, then H2 sections each with a bulleted list of markdown links — ideally `[Title](url): short description`. The structure is what makes it useful; a wall of bare URLs fails the readability check.

```markdown
# Sitemap

## Documentation
- [Getting started](/docs/getting-started.md): install and first deploy
- [Configuration](/docs/configuration.md): every config option explained

## Guides
- [Deploy to production](/guides/production.md)
```

## How do I create a sitemap.md?

For a small site, hand-write it — it's a curation exercise, not a dump of every route. For a site that changes often, generate it at request/build time from the same source as your navigation so it never goes stale:

```typescript
// app/sitemap.md/route.ts
export async function GET() {
  const body = `# Sitemap

## Documentation
` + docs.map((d) => `- [${d.title}](${d.path}): ${d.summary}`).join("\n");
  return new Response(body, {
    headers: { "Content-Type": "text/markdown; charset=utf-8" },
  });
}
```

Keep it curated even when generated: the value is choosing the pages an agent should know about, with a sentence on each.

## Who should ship a sitemap.md?

Any site with more than a handful of pages worth an agent knowing about — docs sites, products with guides, content-heavy marketing sites. If you publish an [llms.txt](https://agent-ready.dev/llms-txt-checker), a sitemap.md is its natural companion. Check whether yours passes with the full [agent-readability score](https://agent-ready.dev/agent-readability-score).

## Frequently asked questions

### What is sitemap.md?

sitemap.md is a markdown file that gives AI agents and humans a curated, structured overview of a site's most important pages — H2 sections grouping descriptive markdown links. It's the readable twin of sitemap.xml: where sitemap.xml is a flat XML list for crawlers, sitemap.md is something an agent can read and cite directly, and a person can browse.

### Is sitemap.md a replacement for sitemap.xml?

No — ship both. sitemap.xml remains the machine index search engines have consumed since 2005 (every URL, with optional lastmod dates). sitemap.md is the agent-facing curated index of your high-value pages. They serve different readers and don't conflict; the two together cover both classic crawlers and AI agents.

### Where do I put a sitemap.md?

Serve it at /sitemap.md (the preferred root location). /docs/sitemap.md and /.well-known/sitemap.md are also recognised. Keep it at a predictable path so an agent can find it without being told where to look.

### What does a good sitemap.md look like?

An H1 title, then H2 sections (Documentation, Guides, API, and so on) each with a bulleted list of markdown links in [Title](url) form — ideally with a short description after a colon. The structure is the point: a flat wall of bare URLs fails the readability check and isn't much use to an agent.

### Do AI scanners check for sitemap.md?

Yes. The Agent Ready scanner checks both that a sitemap.md exists and that it's properly structured (H2 headings plus markdown links). Both are among the most-failed checks across the sites we've scanned — most sites have a sitemap.xml but no markdown sitemap at all.

---

Read the full guide on the web: <https://agent-ready.dev/what-is-sitemap-md>

Scan your site: <https://agent-ready.dev>

## Sitemap

See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.