@@ -9,6 +9,19 @@ import { notFound } from 'next/navigation';
 import { getMDXComponents } from '@/mdx-components';
 import type { Metadata } from 'next';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
+import type { TOCItemType } from 'fumadocs-core/toc';
+import { Children, cloneElement, isValidElement, type ReactNode } from 'react';
+
+// TOC items are rendered as links, so unwrap any links in heading titles to avoid nested <a>
+function stripLinks(node: ReactNode): ReactNode {
+  return Children.map(node, (child) => {
+    if (!isValidElement<{ href?: string; children?: ReactNode }>(child)) return child;
+    const children = stripLinks(child.props.children);
+    return child.props.href != null ? children : cloneElement(child, undefined, children);
+  });
+}
+
+const tocWithoutLinks = (toc: TOCItemType[]) => toc.map((item) => ({ ...item, title: stripLinks(item.title) }));
 
 export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
   const params = await props.params;
@@ -18,7 +31,7 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
   const MDX = page.data.body;
 
   return (
-    <DocsPage toc={page.data.toc} full={page.data.full}>
+    <DocsPage toc={tocWithoutLinks(page.data.toc)} full={page.data.full}>
       <DocsTitle>{page.data.title}</DocsTitle>
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>
 
@@ -34,7 +34,15 @@ export default function Layout({ children }: LayoutProps<'/'>) {
             gtag('config', 'G-JV0T1EB3R7');
           `}
         </Script>
-        <RootProvider>{children}</RootProvider>
+        <RootProvider
+          theme={{
+            // next-themes' inline script only needs to run from SSR; mark it as a data block on the client
+            // to avoid React 19's "Encountered a script tag while rendering React component" dev warning
+            scriptProps: { type: typeof window === 'undefined' ? 'text/javascript' : 'text/plain' },
+          }}
+        >
+          {children}
+        </RootProvider>
       </body>
     </html>
   );
 
@@ -1,5 +1,13 @@
 import Link from 'next/link';
-import { ExternalLink, Github } from 'lucide-react';
+import { ExternalLink } from 'lucide-react';
+
+function GithubIcon({ className }: { className?: string }) {
+    return (
+        <svg className={className} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+            <path d="M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.56v-1.97c-3.2.7-3.87-1.54-3.87-1.54-.52-1.33-1.28-1.69-1.28-1.69-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.03 1.76 2.69 1.25 3.35.96.1-.75.4-1.25.73-1.54-2.55-.29-5.24-1.28-5.24-5.68 0-1.26.45-2.28 1.18-3.09-.12-.29-.51-1.46.11-3.04 0 0 .97-.31 3.17 1.18a11 11 0 0 1 5.77 0c2.2-1.49 3.17-1.18 3.17-1.18.63 1.58.23 2.75.11 3.04.74.81 1.18 1.83 1.18 3.09 0 4.41-2.69 5.38-5.25 5.67.41.36.78 1.06.78 2.14v3.17c0 .31.21.68.8.56A11.5 11.5 0 0 0 23.5 12C23.5 5.65 18.35.5 12 .5Z" />
+        </svg>
+    );
+}
 
 interface TemplateIntroProps {
     image: string;
@@ -45,7 +53,7 @@ export default function TemplateIntro({ image, repo, demo, name }: TemplateIntro
                     rel="noopener noreferrer"
                     className="inline-flex items-center gap-2 px-6 py-2.5 bg-white dark:bg-slate-900 border border-slate-200 dark:border-slate-800 hover:bg-slate-50 dark:hover:bg-slate-800 text-slate-700 dark:text-slate-200 rounded-lg font-medium transition-all shadow-sm hover:shadow-md"
                 >
-                    <Github className="w-4 h-4" />
+                    <GithubIcon className="w-4 h-4" />
                     View Source
                 </a>
             </div>
 
@@ -1,5 +1,5 @@
 'use client';
-import { cn } from 'fumadocs-ui/utils/cn';
+import { cn } from '@/app/lib/utils';
 import React, { useState, useMemo } from 'react';
 
 export interface Template {
 
@@ -1,5 +1,6 @@
 import defaultMdxComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
+import { Children, isValidElement, type ComponentProps, type ReactNode } from 'react';
 import { Info } from '@/components/info';
 import { Tip } from '@/components/tip';
 import { YouTube } from '@/components/youtube';
@@ -8,9 +9,45 @@ import { ScreenshotsGallery } from '@/components/screenshots-gallery';
 import { CopyBlock } from '@/app/components/copy-block';
 import { Pipeline, PipelineStep } from '@/components/pipeline';
 
+const DefaultImg = defaultMdxComponents.img;
+
+// remark-image can emit fractional SVG dimensions, which next/image rejects
+const round = (n?: number | string) => (n == null ? n : Math.round(Number(n)));
+
+const hasLink = (children: ReactNode): boolean =>
+  Children.toArray(children).some(
+    (c) => isValidElement<{ href?: string; children?: ReactNode }>(c) && (c.props.href != null || hasLink(c.props.children)),
+  );
+
+// fumadocs' Heading wraps its children in an anchor link, so headings that are already links
+// would render a nested <a> (invalid HTML that breaks hydration); render those as plain headings
+function heading(as: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6') {
+  const Default = defaultMdxComponents[as];
+  return function LinkSafeHeading(props: ComponentProps<typeof as>) {
+    if (!hasLink(props.children)) return <Default {...props} />;
+    const As = as;
+    return <As {...props} className={['scroll-m-28', props.className].filter(Boolean).join(' ')} />;
+  };
+}
+
+const headings = {
+  h1: heading('h1'),
+  h2: heading('h2'),
+  h3: heading('h3'),
+  h4: heading('h4'),
+  h5: heading('h5'),
+  h6: heading('h6'),
+};
+
+const Img = (props: ComponentProps<typeof DefaultImg>) => (
+  <DefaultImg {...props} width={round(props.width)} height={round(props.height)} />
+);
+
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...defaultMdxComponents,
+    ...headings,
+    img: Img,
     Info,
     Tip,
     YouTube,