--- title: "Docs Benchmark Report: Notion" description: "Notion benchmark report with category scores and check-level detail." canonical: "https://docsalot.dev/benchmarks/docs/notion" human_url: "https://docsalot.dev/benchmarks/docs/notion" markdown_url: "https://docsalot.dev/benchmarks/docs/notion.md" index_url: "https://docsalot.dev/benchmarks/docs" index_markdown_url: "https://docsalot.dev/benchmarks/docs.md" updated: "2026-05-04" --- [Back to docs benchmark index](https://docsalot.dev/benchmarks/docs.md) # Docs Benchmark Report: Notion > Copy this markdown report into a developer ticket or coding agent prompt when you want concrete docs fixes tied to benchmark checks. ## Report Links - Human report: https://docsalot.dev/benchmarks/docs/notion - Markdown report: https://docsalot.dev/benchmarks/docs/notion.md - Benchmark index: https://docsalot.dev/benchmarks/docs - Benchmark index markdown: https://docsalot.dev/benchmarks/docs.md - Public docs URL: https://developers.notion.com/ ## Score Summary - Report for: Notion - Display URL: developers.notion.com - Report type: Public benchmark report - Score: 92 - Grade: A - Summary: Notion scored 92/100 on Mintlify's public score report across 29 published checks. - Checked at: May 4, 2026 at 12:00 AM UTC - Category: Productivity - Source: Mintlify score - Checks passed: 23/29 - Warnings: 2 - Failed checks: 2 - Skipped checks: 2 ## What Already Works - Markdown Availability is relatively strong at 100/100. - Content Structure is relatively strong at 100/100. - URL Stability and Redirects is relatively strong at 100/100. ## What To Improve Next - Page Size Html in Page Size and Truncation Risk. - Markdown Content Parity in Observability and Content Health. - Page Size Markdown in Page Size and Truncation Risk. ## Full Score Breakdown ### Content Discoverability - 98/100 - Question: Can an agent find the right starting point? - Category focus: Checks for llms.txt, sitemaps, and a clear public docs entry point. - Category note: 1 warning across 6 AFDocs checks. - Passed: 5 - Warnings: 1 - Failed: 0 - Skipped: 0 Checks: - PASS - LLMS TXT Exists: llms.txt found at 1 location(s) - WARN - LLMS TXT Valid: llms.txt contains parseable links but doesn't fully follow the proposed structure: https://developers.notion.com/llms.txt: No blockquote summary found Your llms.txt contains parseable links but doesn't follow the standard structure. Add an H1 title as the first line and a blockquote summary (lines starting with >) to improve agent parsing. - PASS - LLMS TXT Size: llms.txt is 24,913 characters (under 50,000 threshold) - PASS - LLMS TXT Links Resolve: All 15 same-origin sampled links resolve (162 total links) - PASS - LLMS TXT Links Markdown: 15/15 same-origin sampled links point to markdown content (100%) (1 external link excluded) - PASS - LLMS TXT Directive: llms.txt directive found in all 15 sampled pages, near the top of content ### Markdown Availability - 100/100 - Question: Can an agent fetch a clean text version of the docs? - Category focus: Checks for markdown routes and clean text delivery without UI-heavy wrappers. - Category note: 2 AFDocs checks pass. - Passed: 2 - Warnings: 0 - Failed: 0 - Skipped: 0 Checks: - PASS - Markdown Url Support: 15/15 sampled pages support .md URLs (100%) - PASS - Content Negotiation: 15/15 sampled pages support content negotiation (100%) ### Page Size and Truncation Risk - 73/100 - Question: Can an agent read the page without losing important context? - Category focus: Checks for oversized pages, noisy navigation, and chunking risks. - Category note: 1 failed and 1 warning across 4 AFDocs checks. - Passed: 2 - Warnings: 1 - Failed: 1 - Skipped: 0 Checks: - PASS - Rendering Strategy: All 15 sampled pages contain server-rendered content - WARN - Page Size Markdown: 2 of 15 pages between 50K–100K chars (max 97K) 2 of 15 markdown pages are between 50K and 100K characters. These may be truncated on some agent platforms or routed through summarization. Consider splitting large pages. - FAIL - Page Size Html: 15 of 15 sampled pages convert to over 100K chars (max 584K, 28% boilerplate) 15 of 15 pages convert to over 100K characters of markdown. Reduce inline CSS/JS, break large pages, or provide markdown versions as a smaller alternative. - PASS - Content Start Position: Content starts within first 10% on all 15 sampled pages (median 9%) ### Content Structure - 100/100 - Question: Can an agent understand how the page is organized? - Category focus: Checks for headings, code block formatting, and readable section hierarchy. - Category note: 1 skipped across 3 AFDocs checks. - Passed: 2 - Warnings: 0 - Failed: 0 - Skipped: 1 Checks: - PASS - Tabbed Content Serialization: 50 tab group(s) across 13 of 15 sampled pages; all serialize under 50K chars - SKIP - Section Header Quality: 13 page(s) with tabs found, but no section headers inside tab panels to evaluate - PASS - Markdown Code Fence Validity: All 43 code fences properly closed across 16 pages ### URL Stability and Redirects - 100/100 - Question: Can an agent trust that URLs will stay predictable? - Category focus: Checks for stable docs URLs and minimal redirect churn on core paths. - Category note: 2 AFDocs checks pass. - Passed: 2 - Warnings: 0 - Failed: 0 - Skipped: 0 Checks: - PASS - Http Status Codes: All 15 sampled pages return proper error codes for bad URLs - PASS - Redirect Behavior: No redirects detected across 15 sampled pages ### Observability and Content Health - 94/100 - Question: Can an agent tell whether the docs are fresh and trustworthy? - Category focus: Checks for freshness signals, content health, and crawl confidence. - Category note: 1 failed across 3 AFDocs checks. - Passed: 2 - Warnings: 0 - Failed: 1 - Skipped: 0 Checks: - PASS - LLMS TXT Freshness: llms.txt covers 100% of 157 sitemap doc pages; 4 llms.txt links not in sitemap (may indicate stale links or incomplete sitemap) - FAIL - Markdown Content Parity: 2 of 15 pages have substantive content differences between markdown and HTML (avg 5% missing) 2 pages have substantive content differences between markdown and HTML (avg 5% missing). Agents receiving the markdown version are getting outdated or incomplete content. Regenerate markdown from source or fix the build pipeline. - PASS - Cache Header Hygiene: All 16 endpoints have appropriate cache headers ### Authentication and Access - 100/100 - Question: Can an agent access the docs without getting blocked? - Category focus: Checks whether public docs stay accessible and auth-gated content is handled clearly. - Category note: 1 skipped across 2 AFDocs checks. - Passed: 1 - Warnings: 0 - Failed: 0 - Skipped: 1 Checks: - PASS - Auth Gate Detection: All 15 sampled pages are publicly accessible - SKIP - Auth Alternative Access: All docs pages are publicly accessible; no alternative access paths needed ### Full Content Discoverability - 100/100 - Question: Can a long-context agent ingest a full docs snapshot directly? - Category focus: Checks whether llms-full.txt exists, is structured correctly, and resolves cleanly. - Category note: llms-full.txt passes all checks. - Passed: 4 - Warnings: 0 - Failed: 0 - Skipped: 0 Checks: - PASS - LLMS Full Exists: Found llms-full.txt. - PASS - LLMS Full Size: llms-full.txt size is within the expected range. - PASS - LLMS Full Valid: llms-full.txt has a recognizable markdown structure. - PASS - LLMS Full Links Resolve: llms-full.txt links resolve successfully. ### Agent Skills - 100/100 - Question: Do these docs publish explicit operating guidance for agents? - Category focus: Checks for a published skill.md or equivalent agent skill definition. - Category note: skill.md passes all checks. - Passed: 1 - Warnings: 0 - Failed: 0 - Skipped: 0 Checks: - PASS - Skill MD: Found an agent skill definition. ### MCP Server - 100/100 - Question: Can an agent discover first-class tools instead of scraping pages? - Category focus: Checks whether a discoverable MCP server and tool surface are published. - Category note: MCP passes all checks. - Passed: 2 - Warnings: 0 - Failed: 0 - Skipped: 0 Checks: - PASS - MCP Server Discoverable: Found an MCP server. - PASS - MCP Tool Count: The MCP server exposes tools. ## Suggested Handoff Ask the developer or coding agent to work through the failed checks and next-step items first, then rerun the benchmark on https://developers.notion.com/ to confirm the score moves in the right direction.