feat(docs): implement great docs improvements inspired by leerob.com #2337

sohamganatra · 2026-01-07T22:47:48Z

Summary

Implements comprehensive documentation improvements following best practices from leerob.com/docs - the gold standard for modern documentation.

What's Changed

Phase 1: Linkable Everything

✅ Stable anchor links for all headings (H1-H6)
✅ Hover-reveal link icon with click-to-copy URL functionality
✅ Skip navigation link for accessibility
✅ JSON-LD TechArticle schema for SEO

Phase 2: Visual Polish

✅ Typography improvements: 65ch line length, generous spacing
✅ Enhanced heading hierarchy with border-bottom on H2
✅ Code block enhancements with language badges
✅ Polished callout components with semantic icons (info, warning, error, success, tip, note, important)

Phase 3: Cross-linking & Discoverability

✅ Related pages component for documentation cross-linking
✅ Inline related links component

Phase 4: Accessibility

✅ Skip navigation link (focus-visible)
✅ Reduced motion support via prefers-reduced-motion
✅ ARIA labels on interactive elements

Phase 5: AI-First Infrastructure

✅ MDX-to-Markdown converter for AI agents
✅ Pure markdown API at /docs/*.mdx
✅ Content negotiation via Accept: text/markdown header
✅ Unified path validation with security protections

New Components

Component	Description
`components/heading-anchor.tsx`	Linkable headings with stable anchors
`components/callout.tsx`	7 callout types with semantic icons
`components/related-pages.tsx`	Cross-linking cards
`components/code-block.tsx`	Enhanced code blocks with language badges
`components/feedback.tsx`	Page feedback component
`components/copy-button.tsx`	Smart copy with API key substitution
`components/code-tabs.tsx`	Language switcher for code examples
`components/ai-search.tsx`	AI-powered search integration
`lib/mdx-to-markdown.ts`	JSX to markdown converter
`lib/path-validation.ts`	Unified security validation
`proxy.ts`	Content negotiation middleware

API Endpoints

GET /api/mdx-content/[...path] - Serves pure markdown for AI agents
POST /api/feedback - Page feedback collection
GET /docs/*.mdx - Pure markdown via URL extension
GET /docs/* + Accept: text/markdown - Content negotiation

Test Plan

🤖 Generated with Claude Code

## Summary Implements comprehensive documentation improvements following best practices from leerob.com/docs - the gold standard for modern documentation. ### Key Changes - Linkable headings with stable anchors and click-to-copy - Skip navigation link for accessibility - JSON-LD TechArticle schema for SEO - Typography improvements (65ch line length, generous spacing) - Polished callout components with semantic icons - Related pages component for cross-linking - MDX-to-Markdown converter for AI agents - Pure markdown API at /docs/*.mdx - Content negotiation via Accept header - Unified path validation with security protections ### New Components - heading-anchor.tsx, callout.tsx, related-pages.tsx - code-block.tsx, feedback.tsx, copy-button.tsx - code-tabs.tsx, ai-search.tsx - lib/mdx-to-markdown.ts, lib/path-validation.ts - proxy.ts (content negotiation) ### API Endpoints - /api/mdx-content/[...path] - Pure markdown for AI - /api/feedback - Page feedback collection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

vercel · 2026-01-07T22:47:53Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
fumadocs	Error		Jan 8, 2026 1:33am

cursor · 2026-01-07T22:52:11Z

fumadocs/app/(home)/docs/[[...slug]]/page.tsx

+    headline: page.data.title,
+    description: page.data.description || '',
+    url: `https://composio.dev${page.url}`,
+    image: getPageImage(page).url,


JSON-LD image uses relative URL instead of absolute

Medium Severity

The JSON-LD structured data sets image to getPageImage(page).url, which returns a relative URL like /og/docs/quickstart/image.png. However, Schema.org JSON-LD requires absolute URLs for the image property for search engines to properly use it. Other URLs in the same object correctly use absolute URLs (e.g., url is set to https://composio.dev${page.url}). The image URL needs to be prefixed with the domain to produce valid structured data that Google and other search engines can consume.

cursor · 2026-01-07T22:52:11Z

fumadocs/app/layout.tsx

+        {/* Skip navigation for accessibility */}
+        <a href="#main-content" className="skip-nav">
+          Skip to main content
+        </a>


Skip navigation link target missing on non-docs pages

Medium Severity

The skip navigation link (href="#main-content") is added to the root layout and appears on all pages, but the target element with id="main-content" is only added to the docs page. On other pages (home, changelog, reference, toolkits), the skip link points to a non-existent element. This causes the accessibility feature to silently fail for keyboard and screen reader users on most pages of the site.

Additional Locations (1)

fumadocs/app/(home)/docs/[[...slug]]/page.tsx#L45-L46

- Fix Zod schema compatibility with fumadocs-mdx internal Zod v4 - Enable tableOfContent in DocsPage component - Add TOCFix client component for XL screen TOC display - Add CSS overrides for TOC sidebar positioning - Remove unnecessary zod dependency from source.config.ts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

cursor · 2026-01-07T23:58:17Z

fumadocs/app/global.css

+/* Mobile nav header styling */
+#nd-nav-mobile {
+  backdrop-filter: blur(12px);
+  background: rgba(var(--color-fd-background), 0.9);


Invalid CSS rgba() syntax with hex color variable

Medium Severity

The CSS rgba(var(--color-fd-background), 0.9) is invalid syntax. The --color-fd-background variable contains a hex color value (#ffffff or #1a1815), but rgba() requires separate RGB numeric values as arguments, not a hex string. This will cause the browser to ignore the entire background declaration, so the mobile navigation header won't have the intended semi-transparent backdrop effect.

The fumadocs grid layout was not properly placing the TOC in the third column. Using fixed positioning ensures the TOC displays correctly in the top-right corner on XL screens (≥1280px). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

AI agents can now request pure markdown content via: - /docs/quickstart.md (in addition to .mdx) - /tool-router/overview.md - etc. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

The custom TOC positioning fixes (fixed positioning, CSS overrides) caused more issues than they solved - main content became invisible. Reverting to fumadocs default behavior which shows TOC at bottom. Removed: - components/toc-fix.tsx (DOM manipulation for fixed TOC) - TOC CSS overrides in global.css - TOCFix import from docs layout 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

The <main id="main-content"> wrapper was breaking fumadocs' grid layout, preventing the TOC from appearing in the right sidebar on XL screens. Replacing with React fragment allows DocsPage to integrate properly with DocsLayout's CSS grid and the layout: variant to work correctly. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

vercel bot deployed to Preview January 7, 2026 22:49 View deployment

cursor bot reviewed Jan 7, 2026

View reviewed changes

vercel bot had a problem deploying to Preview January 7, 2026 23:53 Failure

cursor bot reviewed Jan 7, 2026

View reviewed changes

vercel bot had a problem deploying to Preview January 8, 2026 00:52 Failure

vercel bot had a problem deploying to Preview January 8, 2026 00:53 Failure

vercel bot had a problem deploying to Preview January 8, 2026 00:58 Failure

vercel bot had a problem deploying to Preview January 8, 2026 01:33 Failure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(docs): implement great docs improvements inspired by leerob.com #2337

feat(docs): implement great docs improvements inspired by leerob.com #2337

Uh oh!

sohamganatra commented Jan 7, 2026

Uh oh!

vercel bot commented Jan 7, 2026 •

edited

Loading

Uh oh!

cursor bot Jan 7, 2026

Uh oh!

cursor bot Jan 7, 2026

Uh oh!

cursor bot Jan 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(docs): implement great docs improvements inspired by leerob.com #2337

Are you sure you want to change the base?

feat(docs): implement great docs improvements inspired by leerob.com #2337

Uh oh!

Conversation

sohamganatra commented Jan 7, 2026

Summary

What's Changed

Phase 1: Linkable Everything

Phase 2: Visual Polish

Phase 3: Cross-linking & Discoverability

Phase 4: Accessibility

Phase 5: AI-First Infrastructure

New Components

API Endpoints

Test Plan

Uh oh!

vercel bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor bot Jan 7, 2026

Choose a reason for hiding this comment

JSON-LD image uses relative URL instead of absolute

Uh oh!

cursor bot Jan 7, 2026

Choose a reason for hiding this comment

Skip navigation link target missing on non-docs pages

Uh oh!

cursor bot Jan 7, 2026

Choose a reason for hiding this comment

Invalid CSS rgba() syntax with hex color variable

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Jan 7, 2026 •

edited

Loading