feat: better looking docs

Author: iiAhmedYT

src/components/docs/MDXRenderer.tsx

@@ -120,7 +120,7 @@ function buildMdxComponents(projectId?: string, version?: string) {
     if (!className) {
       return (
         <code
-          className="bg-white/10 text-white px-1.5 py-0.5 rounded font-mono text-[0.9em]"
+          className="code-inline"
           {...props}
         >
           {children}
@@ -264,7 +264,7 @@ export const MDXRenderer = memo(({ content, className, projectId, version }: MDX
 
   if (error) {
     return (
-      <div className={cn('prose prose-invert max-w-none', className)}>
+      <div className={cn('prose prose-invert', className)}>
         <div className="p-4 border border-red-500/50 bg-red-500/10 rounded-lg">
           <h3 className="text-red-400 mb-2">MDX Compilation Error</h3>
           <pre className="text-sm text-red-300 overflow-auto">
@@ -277,16 +277,19 @@ export const MDXRenderer = memo(({ content, className, projectId, version }: MDX
 
   if (!MDXContent) {
     return (
-      <div className={cn('prose prose-invert max-w-none', className)}>
-        <div className="flex items-center justify-center py-8">
-          <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
+      <div className={cn('prose prose-invert', className)}>
+        <div className="space-y-3 py-8">
+          <div className="h-4 bg-muted rounded w-full animate-pulse" />
+          <div className="h-4 bg-muted rounded w-11/12 animate-pulse" />
+          <div className="h-4 bg-muted rounded w-4/5 animate-pulse" />
+          <div className="h-4 bg-muted rounded w-3/4 animate-pulse" />
         </div>
       </div>
     );
   }
 
   return (
-    <div className={cn('prose prose-invert max-w-none', className)}>
+    <div className={cn('prose prose-invert', className)}>
       <MDXContent components={mdxComponents} />
     </div>
   );

src/components/docs/MarkdownRenderer.tsx

@@ -101,7 +101,7 @@ function buildComponents(projectId?: string, version?: string) {
     if (inline || !className) {
       return (
         <code
-          className="bg-white/10 text-white px-1.5 py-0.5 rounded font-mono text-[0.9em]"
+          className="code-inline"
           {...props}
         >
           {children}
@@ -209,7 +209,7 @@ export const MarkdownRenderer = memo(({ content, className, projectId, version }
   const components = useMemo(() => buildComponents(projectId, version), [projectId, version]);
 
   return (
-    <div className={cn('prose prose-invert max-w-none', className)}>
+    <div className={cn('prose prose-invert', className)}>
       <ReactMarkdown
         remarkPlugins={remarkPlugins}
         rehypePlugins={rehypePlugins}

src/components/docs/SmartImg.tsx

@@ -11,7 +11,7 @@
  *  - Defaults to `loading="lazy"` + `decoding="async"`.
  */
 
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useCallback } from 'react';
 
 interface ImageMeta {
   width?: number;
@@ -73,16 +73,13 @@ export function SmartImg({
   ...rest
 }: Props) {
   const resolved = src ? normalizeAssetPath(src) : src;
+  const [erroredImages, setErroredImages] = useState<Set<string>>(new Set());
   const [meta, setMeta] = useState<ImageMeta | undefined>(() =>
     resolved && manifestCache ? manifestCache[resolved] : undefined
   );
 
   useEffect(() => {
     if (!resolved) return;
-    if (manifestCache) {
-      setMeta(manifestCache[resolved]);
-      return;
-    }
     let alive = true;
     loadManifest().then(m => {
       if (alive) setMeta(m[resolved]);
@@ -92,18 +89,42 @@ export function SmartImg({
     };
   }, [resolved]);
 
+  const handleError = useCallback(() => {
+    setErroredImages(prev => {
+      if (!resolved) return prev;
+      const next = new Set(prev);
+      next.add(resolved);
+      return next;
+    });
+  }, [resolved]);
+
   // Explicit width/height props always win; fall back to manifest.
   const finalWidth = width ?? meta?.width;
   const finalHeight = height ?? meta?.height;
 
+  if (!resolved || (resolved && erroredImages.has(resolved))) {
+    return (
+      <span
+        className={`inline-flex items-center gap-1.5 rounded-md bg-muted px-2 py-1 text-xs text-muted-foreground ${className ?? ''}`}
+        role="img"
+        aria-label={alt ?? 'Image failed to load'}
+      >
+        <span aria-hidden="true">&#x1F5BC;</span>
+        {alt || 'Image'}
+      </span>
+    );
+  }
+
   return (
     <img
+      key={resolved}
       src={resolved}
       alt={alt ?? ''}
       width={finalWidth}
       height={finalHeight}
       loading={loading}
       decoding={decoding}
+      onError={handleError}
       className={className}
       {...rest}
     />

src/components/docs/TableOfContents.tsx

@@ -12,12 +12,10 @@ export function TableOfContents({ items, className }: TableOfContentsProps) {
   // 1. Intersection Observer for Scroll Tracking
   const [activeIds, setActiveIds] = useState<string[]>([]);
   const [highlighterStyle, setHighlighterStyle] = useState({ top: 0, height: 0, opacity: 0 });
-  const [tocOffset, setTocOffset] = useState(0);
   const lastActiveIdRef = useRef<string | null>(null);
   const intersectingIdsRef = useRef(new Set<string>());
   const itemsRef = useRef<{ [key: string]: HTMLAnchorElement | null }>({});
   const navRef = useRef<HTMLElement | null>(null);
-  const contentRef = useRef<HTMLDivElement | null>(null);
 
   useEffect(() => {
     const observerOptions = {
@@ -159,20 +157,6 @@ export function TableOfContents({ items, className }: TableOfContentsProps) {
     setHighlighterStyle(s => ({ ...s, opacity: 0 }));
   }, [activeIds, items]);
 
-  useEffect(() => {
-    const activeId = activeIds[activeIds.length - 1];
-    const activeEl = activeId ? itemsRef.current[activeId] : null;
-    const navEl = navRef.current;
-    const contentEl = contentRef.current;
-    if (!activeEl || !navEl || !contentEl) return;
-
-    const activeAnchor = Math.max(36, navEl.clientHeight * 0.28);
-    const activeTop = activeEl.offsetTop;
-    const maxOffset = Math.max(0, contentEl.scrollHeight - navEl.clientHeight);
-
-    setTocOffset(Math.min(Math.max(activeTop - activeAnchor, 0), maxOffset));
-  }, [activeIds]);
-
   const handleClick = (e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
     e.preventDefault();
     const element = document.getElementById(id);
@@ -205,11 +189,7 @@ export function TableOfContents({ items, className }: TableOfContentsProps) {
           className="relative max-h-[calc(100vh-10rem)] overflow-hidden pr-2"
           aria-labelledby="toc-heading"
         >
-          <div
-            ref={contentRef}
-            className="relative transition-transform duration-300 ease-in-out"
-            style={{ transform: `translateY(-${tocOffset}px)` }}
-          >
+          <div className="relative">
             <div
               className="absolute left-0 top-0 bottom-0 w-6 bg-border/40 pointer-events-none transition-all duration-300"
               style={{

src/components/layout/Sidebar.tsx

@@ -86,9 +86,31 @@ interface CategorySectionProps {
   versionId: string;
 }
 
+const CATEGORY_COLORS = [
+  'bg-sky-500',
+  'bg-emerald-500',
+  'bg-violet-500',
+  'bg-amber-500',
+  'bg-rose-500',
+  'bg-cyan-500',
+  'bg-lime-500',
+  'bg-fuchsia-500',
+  'bg-orange-500',
+  'bg-teal-500',
+];
+
+function categoryColorIndex(name: string): number {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = ((hash << 5) - hash) + name.charCodeAt(i);
+  }
+  return Math.abs(hash) % CATEGORY_COLORS.length;
+}
+
 function CategorySection({ category, currentSlug, projectId, versionId }: CategorySectionProps) {
   const [expanded, setExpanded] = useState(true);
   const regionId = `cat-${projectId}-${versionId}-${category.name.replace(/\s+/g, '-').toLowerCase()}`;
+  const dotColor = CATEGORY_COLORS[categoryColorIndex(category.name)];
 
   return (
     <div className="mb-4">
@@ -98,6 +120,7 @@ function CategorySection({ category, currentSlug, projectId, versionId }: Catego
         aria-controls={regionId}
         className="flex items-center gap-1 w-full px-3 py-2 text-sm font-semibold text-muted-foreground hover:text-foreground transition-colors"
       >
+        <span className={`w-1.5 h-1.5 rounded-full shrink-0 ${dotColor}`} aria-hidden="true" />
         {expanded ? (
           <ChevronDown className="h-4 w-4" aria-hidden="true" />
         ) : (
@@ -228,7 +251,8 @@ export function MobileSidebar({ project, version }: { project: DocProject; versi
             <nav aria-label="Documentation sections">
               {version.categories.map((category) => (
                 <div key={category.name} className="mb-4">
-                  <p className="px-3 py-2 text-sm font-semibold text-muted-foreground">
+                  <p className="flex items-center gap-1 px-3 py-2 text-sm font-semibold text-muted-foreground">
+                    <span className={`w-1.5 h-1.5 rounded-full shrink-0 ${CATEGORY_COLORS[categoryColorIndex(category.name)]}`} aria-hidden="true" />
                     {category.name}
                   </p>
                   <ul className="ml-4 space-y-1">

src/index.css

@@ -68,14 +68,14 @@
     --popover: 0 0% 100%;
     --popover-foreground: 222 47% 11%;
 
-    --primary: 190 95% 36%;
+    --primary: 190 95% 28%;
     --primary-foreground: 0 0% 100%;
 
     --secondary: 221 83% 53%;
     --secondary-foreground: 0 0% 100%;
 
     --muted: 214 32% 94%;
-    --muted-foreground: 215 16% 40%;
+    --muted-foreground: 215 16% 35%;
 
     --accent: 210 40% 94%;
     --accent-foreground: 222 47% 11%;
@@ -218,16 +218,25 @@
   }
 
   @keyframes fadeIn {
-    from {
-      opacity: 0;
-      transform: translateY(10px);
+      from {
+        opacity: 0;
+        transform: translateY(6px);
+      }
+
+      to {
+        opacity: 1;
+        transform: translateY(0);
+      }
     }
 
-    to {
-      opacity: 1;
-      transform: translateY(0);
+    @media (prefers-reduced-motion: reduce) {
+      .fade-in {
+        animation: none;
+      }
+      .animate-fadein {
+        animation: none;
+      }
     }
-  }
 
   .animate-lightning {
     stroke-dasharray: 400;
@@ -315,6 +324,20 @@
     text-wrap: balance;
   }
 
+  .code-inline {
+    background: rgba(255, 255, 255, 0.1);
+    color: hsl(var(--foreground));
+    padding: 0.15em 0.4em;
+    border-radius: 0.375rem;
+    font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace);
+    font-size: 0.9em;
+  }
+
+  .light .code-inline {
+    background: rgba(0, 0, 0, 0.08);
+    color: hsl(var(--foreground));
+  }
+
   /* Hide scrollbar but keep functionality */
   .scrollbar-hide {
     -ms-overflow-style: none;

src/pages/Docs.tsx

@@ -57,10 +57,22 @@ export function Docs() {
       <div className="min-h-screen flex flex-col bg-docs">
         <Header />
         <div className="flex-1 container mx-auto px-4 flex items-center justify-center">
-          <div className="text-center">
-            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4"></div>
-            <p className="text-muted-foreground">Loading documentation...</p>
-          </div>
+            <div className="w-full max-w-4xl mx-auto py-12">
+              <div className="flex gap-8 mb-10">
+                <div className="hidden lg:block w-64 shrink-0 space-y-3">
+                    {[75, 55, 65, 45, 60].map((w, i) => (
+                    <div key={i} className="h-4 bg-muted rounded animate-pulse" style={{ width: `${w}%` }} />
+                  ))}
+                </div>
+                <div className="flex-1 space-y-4">
+                  <div className="h-6 bg-muted rounded w-48 animate-pulse mb-2" />
+                  <div className="h-10 bg-muted rounded w-3/4 animate-pulse" />
+                  <div className="h-4 bg-muted rounded w-full animate-pulse" />
+                  <div className="h-4 bg-muted rounded w-5/6 animate-pulse" />
+                  <div className="h-4 bg-muted rounded w-4/6 animate-pulse" />
+                </div>
+              </div>
+            </div>
         </div>
         <Footer />
       </div>
@@ -178,17 +190,23 @@ export function Docs() {
             </div>
 
             {isLoading ? (
-              <div className="py-20 text-center">
-                <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary mx-auto mb-4"></div>
-                <p className="text-muted-foreground">Loading page...</p>
+              <div className="py-12 space-y-4">
+                <div className="h-4 bg-muted rounded w-40 animate-pulse mb-6" />
+                <div className="h-10 bg-muted rounded w-3/5 animate-pulse mb-4" />
+                <div className="h-4 bg-muted rounded w-full animate-pulse" />
+                <div className="h-4 bg-muted rounded w-11/12 animate-pulse" />
+                <div className="h-4 bg-muted rounded w-4/5 animate-pulse" />
+                <div className="h-4 bg-muted rounded w-full animate-pulse" />
+                <div className="h-4 bg-muted rounded w-3/4 animate-pulse" />
+                <div className="h-4 bg-muted rounded w-5/6 animate-pulse" />
               </div>
             ) : !doc ? (
               <div className="py-20 text-center">
                 <p className="text-4xl font-bold mb-4">404</p>
                 <p className="text-muted-foreground">This page doesn&apos;t exist.</p>
               </div>
             ) : (
-              <div key={slug} className="animate-fadein">
+              <div key={slug} className="animate-fadein mx-auto max-w-4xl">
                 {/* Document Header */}
                 <div className="mb-8">
                   {breadcrumbs && <Breadcrumbs items={breadcrumbs} className="mb-4" />}