- [ Home ](/) / - [ Blog ](/blog/) / - llms.txt v2 migration: a practical checklist # `llms.txt` v2 migration: a practical checklist Version 2 changes discovery and scope more than file syntax. This checklist separates required structure from optional, testable improvements. Last updated: August 16, 2026 On this page - [ What changed in llms.txt v2? ](#what-changed-in-llmstxt-v2) - [ Inventory before changing anything ](#inventory-before-changing-anything) - [ The migration sequence ](#the-migration-sequence) - [ Verification and limits ](#verification-and-limits) Version 2 does not turn llms.txt into a Google ranking factor. It expands the proposal from one root file into a path-aware discovery system for agents. Migrate only if compatible agents are part of your use case, and preserve the existing file while you test the new pieces. **Key takeaways** - The H1 remains the only required part of the file. - A more specific path file can describe only the pages below that path. - Markdown alternates and `describedby` are discovery aids, not Search signals. ## What changed in llms.txt v2? The proposal now allows an `llms.txt` at the origin root or at any path. `/docs/llms.txt`, for example, can describe `/docs/` while the root file describes the wider site. When several files could apply, an agent should use the most specific one. V2 also proposes clean Markdown versions of pages. A page can expose that version with `rel="alternate" type="text/markdown"` and identify its applicable map with `rel="describedby"`. These relations may appear in HTML or in an HTTP `Link` header. The file format itself remains deliberately small. An H1 is required. The summary, explanatory preamble, H2 sections and link descriptions are optional. `Optional` remains a useful editorial heading, but v2 assigns it no special processing semantics. Review the [format reference](/llms-txt-format/) before tightening a validator beyond the published rules. ## Inventory before changing anything Start by recording every current file, redirect, content type, and consumer. A root file returning HTTP 200 today should keep returning 200 during migration. Changing its URL merely to adopt v2 would break clients that already know the root convention. Map the site into genuinely distinct scopes. A documentation tree may justify `/docs/llms.txt`; a five-page marketing site probably does not. Path files should reduce irrelevant context, not duplicate the root file word for word. Check whether clean Markdown already exists. Do not advertise an alternate that is a thin conversion, an error page, or stale content. The HTML page remains canonical for Search; the Markdown resource is a machine-readable representation for compatible clients. ## The migration sequence - Validate the existing root file with the [llms.txt validator](/validator/). - Keep its stable URL and correct only genuine syntax errors. - Define each path scope and create a smaller file only where the content boundary is real. - Generate Markdown from the same source as HTML to prevent editorial drift. - Add `alternate` and `describedby` relations to the HTML template. - Test HTTP status, content type, redirects, and linked URLs in CI. - Release on a small scope, inspect server logs, then expand. The [best-practice guide](/best-practices/) covers curation and security beyond syntax. For production patterns, compare against [verified examples](/examples/) without assuming that publication proves consumption. ## Verification and limits Our 12 August 2026 benchmark checked 294 pages linked from 113 H1-first root responses. Thirty-one of the 286 reachable pages advertised a Markdown alternate, and four exposed `rel="describedby"`. That is a baseline of observable implementation, not evidence that agents prefer either relation. Google states that Search does not use llms.txt or other special AI text files. A successful migration therefore means stable resources, correct scope, clean discovery, and measurable requests from relevant clients. It does not mean improved rankings. ### Must I replace my existing root file? No. V2 keeps the root location and adds path-level options. Preserve stable URLs unless a documented defect requires a change. ### Is every HTML page required to have Markdown? No. Markdown alternates are proposed for pages where clean text helps agents. Visual or interactive pages may have no useful equivalent. ### Should the Markdown URL be indexed by Google? Google may crawl many file types, but does not give these files special treatment. Keep the HTML canonical and avoid claiming a ranking benefit. ## Sources - [ llmstxt.org, The /llms.txt file v2 ](https://llmstxt.org/) - [ Google Search Central, generative AI optimization guide ](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)