Add llms.txt for AI-friendly documentation discovery by jfversluis · Pull Request #3202 · dotnet/docs-maui

jfversluis · 2026-02-10T13:39:58Z

Summary

Adds a full hierarchy of llms.txt files to the .NET MAUI docs set, following the llmstxt.org spec, to make the documentation AI-friendly and enable structured discovery by AI assistants and LLM-powered tools.

What's included

Root files (updated)

docs/llms.txt — compact navigator with routing guide, subtopics, nested deep dives, and AI assistant guidance
docs/llms-full.txt — hierarchy-aligned aggregate for tools that can't follow subtopic links; HTML comment markers replaced with natural H2 headings

Area subtopics (new)

File	Coverage
docs/get-started/llms.txt	Setup, SDK, first app, environment issues
docs/fundamentals/llms.txt	Architecture, MVVM, Shell, lifecycle, resources
docs/user-interface/llms.txt	Controls, layouts, handlers, styles, theming
docs/xaml/llms.txt	XAML syntax, namespaces, markup extensions, compilation, source generation
docs/platform-integration/llms.txt	Permissions, storage, sensors, networking, auth
docs/data-cloud/llms.txt	REST, SQLite, push notifications, Aspire
docs/deployment/llms.txt	Publish, performance, trimming, Native AOT
docs/whats-new/llms.txt	.NET 10 and .NET 11 changes, deprecations, migration guidance

Nested deep dives (new)

File	Coverage
docs/fundamentals/data-binding/llms.txt	Compiled bindings, modes, converters, relative bindings
docs/fundamentals/shell/llms.txt	Route registration, navigation, tabs, flyout, lifecycle
docs/user-interface/controls/llms.txt	Control selection, list patterns, obsolete replacements
docs/user-interface/controls/collectionview/llms.txt	Data, templates, layout, selection, grouping, scrolling
docs/user-interface/layouts/llms.txt	Grid, StackLayout variants, FlexLayout, BindableLayout, perf
docs/user-interface/handlers/llms.txt	Handler model, AppendToMapping, custom controls
docs/platform-integration/appmodel/llms.txt	Permissions, main thread, launcher, browser, app metadata
docs/platform-integration/storage/llms.txt	File picker, app directories, preferences, secure storage
docs/platform-integration/communication/llms.txt	Networking, web auth, email, SMS, phone dialer, contacts

README (updated)

Added LLMS Files section explaining hierarchy, routing, and validation

Hierarchy design

docs/llms.txt ← root navigator + routing guide docs/llms-full.txt ← aggregate (for tools that can't follow links) docs/{area}/llms.txt ← area subtopics (8 files) docs/{area}/{topic}/llms.txt ← nested deep dives (9 files)

Each file follows the llmstxt.org spec (H1 → blockquote summary → H2 link sections), includes a Guidance for AI assistants section with imperative best-practice bullets, and an Optional section last.

Key guidance baked in

CollectionView over ListView; Border over Frame; handlers over renderers
Compiled bindings with \x:DataType\ on pages and data templates
Shell as the default navigation model
.NET 10 deprecations: \ClickGestureRecognizer\ removed, \ListView/\TableView\ deprecated, \MessagingCenter\ internal, animation *Async\ methods preferred
XAML source generation (\MauiXamlInflator=SourceGen) recommended in .NET 10

Validation

All 18 llms.txt files validated with \docs/tools/verify-llms.ps1\ (0 errors / 0 warnings).

Internal previews

📄 File	🔗 Preview link
docs/deployment/performance-best-practices.md	docs/deployment/performance-best-practices
docs/user-interface/controls/collectionview/collectionview-guide.md	docs/user-interface/controls/collectionview/collectionview-guide
docs/user-interface/handlers/handler-architecture.md	docs/user-interface/handlers/handler-architecture

Introduces a /llms.txt file following the llmstxt.org specification to make .NET MAUI documentation more discoverable and effective for LLMs and AI-powered tools. The file provides a curated, structured overview of the most important documentation pages organized by topic area. Includes critical anti-pattern guidance (obsolete controls like ListView, TableView, Frame; layout pitfalls) and control selection recommendations informed by community best practices.

Add handler architecture, CollectionView, and performance best practices guides as primary entries in their respective sections. Move the detailed handler reference pages (create, customize) to the Optional section since the guide covers those topics comprehensively.

docs/llms.txt

Address review feedback: link to raw markdown files on GitHub instead of rendered HTML pages. Raw markdown is cleaner for LLM consumption — no navigation chrome, JavaScript, or HTML conversion artifacts. All URLs now follow the pattern: https://raw.githubusercontent.com/dotnet/docs-maui/refs/heads/main/docs/...

Three new standalone guides with inline code examples, no external snippet references or moniker ranges, designed to be fully self-contained for both human readers and LLM consumption: - Handler architecture: what handlers are, creating custom controls, customizing existing controls via Mapper, lifecycle, common recipes - CollectionView: data binding, layouts (list/grid), selection, grouping, empty views, scrolling, SwipeView, performance tips - Performance best practices: compiled bindings, control selection (Grid vs StackLayout, CollectionView vs ListView, Border vs Frame), layout optimization, images, startup, async/threading, memory, trimming/AOT

docs/llms.txt

All link entries now use plain text consistently, addressing review feedback about bold formatting only appearing on some links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Complete structural rewrite of llms.txt based on LLM attention research - Add deprecation substitution table (structured format over prose) - Add numbered architecture and layout rules with consequence framing - Add 5 inline code patterns (MauiProgram, CollectionView, Shell nav, handlers, MVVM) - Reduce curated links from ~116 to ~60 highest-value references - Add recency anchor restating critical constraints at file end - Fix accuracy issues: Effects not deprecated, BackgroundColor not obsolete, Shell QueryProperty behavior, image asset references - Create llms-full.txt companion (191KB) with 8 inlined key docs - Fix Frame to Border in collectionview-guide.md code examples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-03-10T10:20:48Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-03-10T10:20:57Z

Learn Build status updates of commit 4bdd611:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/user-interface/controls/collectionview/collectionview-guide.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/deployment/performance-best-practices.md	✅Succeeded	View (>=net-maui-8.0)
docs/llms-full.txt	✅Succeeded
docs/llms.txt	✅Succeeded
docs/user-interface/handlers/handler-architecture.md	✅Succeeded	View (>=net-maui-8.0)

docs/user-interface/controls/collectionview/collectionview-guide.md

Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

learn-build-service-prod · 2026-03-10T10:21:57Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-03-10T10:22:14Z

Learn Build status updates of commit 8991b38:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/user-interface/controls/collectionview/collectionview-guide.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/deployment/performance-best-practices.md	✅Succeeded	View (>=net-maui-8.0)
docs/llms-full.txt	✅Succeeded
docs/llms.txt	✅Succeeded
docs/user-interface/handlers/handler-architecture.md	✅Succeeded	View (>=net-maui-8.0)

docs/user-interface/controls/collectionview/collectionview-guide.md

Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Add 18 llms.txt files following the llmstxt.org spec across the full .NET MAUI docs set, providing structured discovery for AI assistants. ## New files Area subtopics (first-level routing): - docs/get-started/llms.txt - docs/fundamentals/llms.txt - docs/user-interface/llms.txt - docs/platform-integration/llms.txt - docs/data-cloud/llms.txt - docs/deployment/llms.txt - docs/xaml/llms.txt - docs/whats-new/llms.txt Nested deep dives (high-density topic retrieval): - docs/fundamentals/data-binding/llms.txt - docs/fundamentals/shell/llms.txt - docs/user-interface/controls/llms.txt - docs/user-interface/controls/collectionview/llms.txt - docs/user-interface/layouts/llms.txt - docs/user-interface/handlers/llms.txt - docs/platform-integration/appmodel/llms.txt - docs/platform-integration/storage/llms.txt - docs/platform-integration/communication/llms.txt ## Updated files - docs/llms.txt: rewritten as compact navigator with routing guide, subtopics (incl. XAML and What's New), nested deep dives, and AI assistant guidance - docs/llms-full.txt: rewritten as hierarchy-aligned aggregate; HTML comment markers replaced with natural H2 headings; Communication, XAML, and What's New index sections added - README.md: LLMS Files section added explaining hierarchy and routing

learn-build-service-prod · 2026-03-17T13:14:17Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-03-17T13:15:14Z

Learn Build status updates of commit d446bf5:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/user-interface/controls/collectionview/collectionview-guide.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/data-cloud/llms.txt	✅Succeeded
docs/deployment/llms.txt	✅Succeeded
docs/deployment/performance-best-practices.md	✅Succeeded	View (>=net-maui-8.0)
docs/fundamentals/data-binding/llms.txt	✅Succeeded
docs/fundamentals/llms.txt	✅Succeeded
docs/fundamentals/shell/llms.txt	✅Succeeded
docs/get-started/llms.txt	✅Succeeded
docs/llms-full.txt	✅Succeeded
docs/llms.txt	✅Succeeded
docs/platform-integration/appmodel/llms.txt	✅Succeeded
docs/platform-integration/communication/llms.txt	✅Succeeded
docs/platform-integration/llms.txt	✅Succeeded
docs/platform-integration/storage/llms.txt	✅Succeeded
docs/user-interface/controls/collectionview/llms.txt	✅Succeeded
docs/user-interface/controls/llms.txt	✅Succeeded
docs/user-interface/handlers/handler-architecture.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/handlers/llms.txt	✅Succeeded
docs/user-interface/layouts/llms.txt	✅Succeeded
docs/user-interface/llms.txt	✅Succeeded
docs/whats-new/llms.txt	✅Succeeded
docs/xaml/llms.txt	✅Succeeded
README.md	✅Succeeded

docs/user-interface/controls/collectionview/collectionview-guide.md

Line 0, Column 0: [Suggestion: filename-incomplete - See documentation] The filename contains an incomplete word, misspelled word, acronym, or abbreviation that is disallowed.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

jfversluis requested a review from a team as a code owner February 10, 2026 13:39