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.

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

sitemap.mdis 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. It’s the readable twin of sitemap.xml: 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 exactly why “no sitemap.md” is one of the most common agent-readability mistakes.

sitemap.md vs sitemap.xml

They’re 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 — the preferred root location. /docs/sitemap.md and /.well-known/sitemap.md are also recognised. The point of a well-known path is that an agent can find the file without being told where to look, so a predictable location matters more than the exact one.

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 and tells an agent nothing.

# Sitemap

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

## Guides
- [Deploy to production](/guides/production.md)
- [Set up CI](/guides/ci.md)

## API
- [REST API reference](/docs/api.md): endpoints, auth, and examples

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 anything that changes often, generate it at request or build time from the same source of truth as your navigation, so it never goes stale:

// 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 in choosing the pages an agent should know about, with a sentence on what each one is.

Who should ship a sitemap.md?

Any site with more than a handful of pages worth an agent knowing about — documentation sites, products with guides, content-heavy marketing sites. If you publish an llms.txt, a sitemap.md is its natural companion: llms.txt curates content for LLM consumption, sitemap.md gives the navigable index. Check whether yours passes with the full 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.