Add llms.txt for AI-friendly documentation discovery#3202
Add llms.txt for AI-friendly documentation discovery#3202jfversluis wants to merge 12 commits intomainfrom
Conversation
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.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
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.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
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://github.com/dotnet/docs-maui/refs/heads/main/docs/...
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
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
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
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>
This comment was marked as outdated.
This comment was marked as outdated.
1 similar comment
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as off-topic.
This comment was marked as off-topic.
- 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>
PoliCheck Scan ReportThe 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 foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 4bdd611: 💡 Validation status: suggestions
docs/user-interface/controls/collectionview/collectionview-guide.md
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. |
PoliCheck Scan ReportThe 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 foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 8991b38: 💡 Validation status: suggestions
docs/user-interface/controls/collectionview/collectionview-guide.md
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
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
PoliCheck Scan ReportThe 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 foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
Review: Split this PRThanks for the work here, Gerald. I want to offer a critical perspective and a concrete suggestion. The 3 guide documents are genuinely valuable — merge them nowThe substantive documentation additions stand on their own merit regardless of the llms.txt initiative:
These are real, durable content that helps developers today. I'm going to split these out into separate PRs so they can move forward independently. The llms.txt files need more scrutinyI have several concerns about the 18 llms.txt files:
Recommendation
Without those answers, this is speculative infrastructure with ongoing maintenance cost and zero proven ROI. |
Split from dotnet#3202. Comprehensive guide covering startup performance, layout optimization, binding overhead, image handling, and platform-specific tuning for .NET MAUI applications. Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Split from dotnet#3202. Covers data population, templates, layout configuration, selection, grouping, scrolling, empty views, and migration from ListView for .NET MAUI CollectionView. Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Split from dotnet#3202. Covers the handler model, property/command mappers, AppendToMapping/ModifyMapping patterns, creating custom handlers, and migration from Xamarin.Forms renderers. Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Thank you David's Copilot. Let's hold off on this for now! |
3 participants
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)
Area subtopics (new)
Nested deep dives (new)
README (updated)
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
Validation
All 18 llms.txt files validated with \docs/tools/verify-llms.ps1\ (0 errors / 0 warnings).
Internal previews