From aae3763ddb8aa5516fa8b3bfc724124fbdeef928 Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Mon, 12 Jan 2026 10:28:59 -0800
Subject: [PATCH 1/3] feat: add framework support to documentation components

---
 src/components/Doc.tsx                        |  14 +++
 src/components/Toc.tsx                        |  16 ++-
 .../$version.docs.framework.$framework.$.tsx  |   3 +-
 src/utils/markdown/plugins/collectHeadings.ts |  28 +++++
 .../plugins/transformFrameworkComponent.ts    | 101 +++++++++++-------
 src/utils/markdown/processor.ts               |   7 +-
 6 files changed, 122 insertions(+), 47 deletions(-)

diff --git a/src/components/Doc.tsx b/src/components/Doc.tsx
index 76d6c94ce..c099efbb0 100644
--- a/src/components/Doc.tsx
+++ b/src/components/Doc.tsx
@@ -9,6 +9,8 @@ import { renderMarkdown } from '~/utils/markdown'
 import { DocBreadcrumb } from './DocBreadcrumb'
 import { MarkdownContent } from '~/components/markdown'
 import type { ConfigSchema } from '~/utils/config'
+import { useLocalCurrentFramework } from './FrameworkSelect'
+import { useParams } from '@tanstack/react-router'
 
 type DocProps = {
   title: string
@@ -28,6 +30,8 @@ type DocProps = {
   config?: ConfigSchema
   // Footer content rendered after markdown
   footer?: React.ReactNode
+  // Optional framework to use (overrides URL and local storage)
+  framework?: string
 }
 
 export function Doc({
@@ -45,6 +49,7 @@ export function Doc({
   pagePath,
   config,
   footer,
+  framework: frameworkProp,
 }: DocProps) {
   // Extract headings synchronously during render to avoid hydration mismatch
   const { headings, markup } = React.useMemo(
@@ -52,6 +57,14 @@ export function Doc({
     [content],
   )
 
+  // Get current framework from prop, URL params, or local storage
+  const { framework: paramsFramework } = useParams({ strict: false })
+  const localCurrentFramework = useLocalCurrentFramework()
+  const currentFramework = React.useMemo(() => {
+    const fw = frameworkProp || paramsFramework || localCurrentFramework.currentFramework || 'react'
+    return typeof fw === 'string' ? fw.toLowerCase() : fw
+  }, [frameworkProp, paramsFramework, localCurrentFramework.currentFramework])
+
   const isTocVisible = shouldRenderToc && headings.length > 1
 
   const markdownContainerRef = React.useRef<HTMLDivElement>(null)
@@ -170,6 +183,7 @@ export function Doc({
               colorFrom={colorFrom}
               colorTo={colorTo}
               textColor={textColor}
+              currentFramework={currentFramework}
             />
           </div>
         )}
diff --git a/src/components/Toc.tsx b/src/components/Toc.tsx
index b4c4f84ce..9f2e59669 100644
--- a/src/components/Toc.tsx
+++ b/src/components/Toc.tsx
@@ -18,9 +18,21 @@ type TocProps = {
   colorTo?: string
   textColor?: string
   activeHeadings: Array<string>
+  currentFramework?: string
 }
 
-export function Toc({ headings, textColor, activeHeadings }: TocProps) {
+export function Toc({ headings, textColor, activeHeadings, currentFramework }: TocProps) {
+  // Filter headings based on framework scope
+  const visibleHeadings = React.useMemo(() => {
+    return headings.filter((heading) => {
+      console.log(heading)
+      if (heading.framework) {
+        return currentFramework && heading.framework === currentFramework.toLowerCase()
+      }
+      // If no framework attribute, always show (not framework-scoped)
+      return true
+    })
+  }, [headings, currentFramework])
   return (
     <nav className="flex flex-col sticky top-[var(--navbar-height)] max-h-[calc(100dvh-var(--navbar-height))] overflow-hidden">
       <div className="py-1">
@@ -33,7 +45,7 @@ export function Toc({ headings, textColor, activeHeadings }: TocProps) {
           'py-1 flex flex-col overflow-y-auto text-[.6em] lg:text-[.65em] xl:text-[.7em] 2xl:text-[.75em]',
         )}
       >
-        {headings?.map((heading) => (
+        {visibleHeadings?.map((heading) => (
           <li
             key={heading.id}
             className={twMerge('w-full', headingLevels[heading.level])}
diff --git a/src/routes/$libraryId/$version.docs.framework.$framework.$.tsx b/src/routes/$libraryId/$version.docs.framework.$framework.$.tsx
index c57a891fb..de56d7d3e 100644
--- a/src/routes/$libraryId/$version.docs.framework.$framework.$.tsx
+++ b/src/routes/$libraryId/$version.docs.framework.$framework.$.tsx
@@ -67,7 +67,7 @@ export const Route = createFileRoute(
 function Docs() {
   const { title, content, filePath } = Route.useLoaderData()
   const { config } = docsRouteApi.useLoaderData()
-  const { version, libraryId } = Route.useParams()
+  const { version, libraryId, framework } = Route.useParams()
   const library = getLibrary(libraryId)
   const branch = getBranch(library, version)
   const location = useLocation()
@@ -89,6 +89,7 @@ function Docs() {
         libraryVersion={version === 'latest' ? library.latestVersion : version}
         pagePath={location.pathname}
         config={config}
+        framework={framework}
       />
     </DocContainer>
   )
diff --git a/src/utils/markdown/plugins/collectHeadings.ts b/src/utils/markdown/plugins/collectHeadings.ts
index 852b604af..19fe023e1 100644
--- a/src/utils/markdown/plugins/collectHeadings.ts
+++ b/src/utils/markdown/plugins/collectHeadings.ts
@@ -7,6 +7,7 @@ export type MarkdownHeading = {
   id: string
   text: string
   level: number
+  framework?: string
 }
 
 type HastElement = {
@@ -38,6 +39,14 @@ const isTabsAncestor = (ancestor: HastElement) => {
   return typeof component === 'string' && component.toLowerCase() === 'tabs'
 }
 
+const isFrameworkPanelAncestor = (ancestor: HastElement) => {
+  if (ancestor.type !== 'element') {
+    return false
+  }
+
+  return ancestor.tagName === 'md-framework-panel'
+}
+
 export function rehypeCollectHeadings(initialHeadings?: MarkdownHeading[]) {
   const headings = initialHeadings ?? []
 
@@ -62,10 +71,29 @@ export function rehypeCollectHeadings(initialHeadings?: MarkdownHeading[]) {
         return
       }
 
+      let currentFramework: string | undefined
+
+      const headingDataFramework = node.properties?.['data-framework']
+      if (typeof headingDataFramework === 'string') {
+        currentFramework = headingDataFramework
+      } else if (Array.isArray(ancestors)) {
+        const frameworkPanel = ancestors.find((ancestor) =>
+          isFrameworkPanelAncestor(ancestor as HastElement),
+        ) as HastElement | undefined
+
+        if (frameworkPanel) {
+          const dataFramework = frameworkPanel.properties?.['data-framework']
+          if (typeof dataFramework === 'string') {
+            currentFramework = dataFramework
+          }
+        }
+      }
+
       headings.push({
         id,
         level: Number(node.tagName.substring(1)),
         text: toString(node as any).trim(),
+        framework: currentFramework,
       })
     })
 
diff --git a/src/utils/markdown/plugins/transformFrameworkComponent.ts b/src/utils/markdown/plugins/transformFrameworkComponent.ts
index 50f3f83fa..8d95c1eb3 100644
--- a/src/utils/markdown/plugins/transformFrameworkComponent.ts
+++ b/src/utils/markdown/plugins/transformFrameworkComponent.ts
@@ -1,20 +1,20 @@
 import { toString } from 'hast-util-to-string'
 import { visit } from 'unist-util-visit'
 
-import { isHeading, normalizeComponentName } from './helpers'
+import { normalizeComponentName } from './helpers'
 
 type HastNode = {
   type: string
-  tagName: string
+  tagName?: string
   properties?: Record<string, unknown>
   children?: HastNode[]
+  value?: string
 }
 
 type FrameworkCodeBlock = {
   title: string
   code: string
   language: string
-  preNode: HastNode
 }
 
 type FrameworkExtraction = {
@@ -22,29 +22,14 @@ type FrameworkExtraction = {
   contentByFramework: Record<string, HastNode[]>
 }
 
-// Helper to extract text from nodes (used for code content)
-function extractText(nodes: any[]): string {
-  let text = ''
-  for (const node of nodes) {
-    if (node.type === 'text') {
-      text += node.value
-    } else if (node.type === 'element' && node.children) {
-      text += extractText(node.children)
-    }
-  }
-  return text
-}
-
 /**
  * Extract code block data (language, title, code) from a <pre> element.
- * Extracts title from data-code-title (set by rehypeCodeMeta).
  */
 function extractCodeBlockData(preNode: HastNode): {
   language: string
   title: string
   code: string
 } | null {
-  // Find the <code> child
   const codeNode = preNode.children?.find(
     (c: HastNode) => c.type === 'element' && c.tagName === 'code',
   )
@@ -61,6 +46,7 @@ function extractCodeBlockData(preNode: HastNode): {
     }
   }
 
+  // Extract title from data attributes
   let title = ''
   const props = preNode.properties || {}
   if (typeof props['dataCodeTitle'] === 'string') {
@@ -73,57 +59,93 @@ function extractCodeBlockData(preNode: HastNode): {
     title = props['data-filename']
   }
 
-  // Extract code content
+  // Extract code text
+  const extractText = (nodes: HastNode[]): string => {
+    let text = ''
+    for (const node of nodes) {
+      if (node.type === 'text' && node.value) {
+        text += node.value
+      } else if (node.type === 'element' && node.children) {
+        text += extractText(node.children)
+      }
+    }
+    return text
+  }
   const code = extractText(codeNode.children || [])
 
   return { language, title, code }
 }
 
-/**
- * Extract framework-specific content for framework component.
- * Groups all content (code blocks and general content) by framework headings.
- */
 function extractFrameworkData(node: HastNode): FrameworkExtraction | null {
   const children = node.children ?? []
   const codeBlocksByFramework: Record<string, FrameworkCodeBlock[]> = {}
   const contentByFramework: Record<string, HastNode[]> = {}
 
-  let currentFramework: string | null = null
+  // First pass: find the first H1 to determine the first framework
+  let firstFramework: string | null = null
+  for (const child of children) {
+    if (child.type === 'element' && child.tagName === 'h1') {
+      firstFramework = toString(child as any).trim().toLowerCase()
+      break
+    }
+  }
+
+  // If no H1 found at all, return null
+  if (!firstFramework) {
+    return null
+  }
+
+  // Second pass: collect content
+  let currentFramework: string | null = firstFramework // Start with first framework for content before first H1
+
+  // Initialize the first framework
+  contentByFramework[firstFramework] = []
+  codeBlocksByFramework[firstFramework] = []
 
   for (const child of children) {
-    if (isHeading(child)) {
+    // Check if this is an H1 heading (framework divider)
+    if (child.type === 'element' && child.tagName === 'h1') {
+      // Extract framework name from H1 text
       currentFramework = toString(child as any)
         .trim()
         .toLowerCase()
+
       // Initialize arrays for this framework
       if (currentFramework && !contentByFramework[currentFramework]) {
         contentByFramework[currentFramework] = []
         codeBlocksByFramework[currentFramework] = []
       }
+      // Don't include the H1 itself in content - it's just a divider
       continue
     }
 
-    // Skip if no framework heading found yet
     if (!currentFramework) continue
 
-    // Add all content to contentByFramework
-    contentByFramework[currentFramework].push(child)
+    // Create a shallow copy of the node
+    const contentNode = Object.assign({}, child) as HastNode
+
+    // Mark all headings (h2-h6) with framework attribute so they appear in TOC only for this framework
+    if (
+      contentNode.type === 'element' &&
+      contentNode.tagName &&
+      /^h[2-6]$/.test(contentNode.tagName)
+    ) {
+      contentNode.properties = (contentNode.properties || {}) as Record<string, unknown>
+      contentNode.properties['data-framework'] = currentFramework
+    }
 
-    // Look for <pre> elements (code blocks) under current framework
-    if ((child as any).type === 'element' && (child as any).tagName === 'pre') {
-      const codeBlockData = extractCodeBlockData(child)
-      if (!codeBlockData) continue
+    contentByFramework[currentFramework].push(contentNode)
 
-      codeBlocksByFramework[currentFramework].push({
-        title: codeBlockData.title || 'Untitled',
-        code: codeBlockData.code,
-        language: codeBlockData.language,
-        preNode: child,
-      })
+    // Extract code blocks for this framework
+    if (contentNode.type === 'element' && contentNode.tagName === 'pre') {
+      const codeBlockData = extractCodeBlockData(contentNode)
+      if (codeBlockData) {
+        codeBlocksByFramework[currentFramework].push(codeBlockData)
+      }
     }
   }
 
-  // Return null only if no frameworks found at all
+  // Return null if no frameworks found
   if (Object.keys(contentByFramework).length === 0) {
     return null
   }
@@ -188,3 +210,4 @@ export const rehypeTransformFrameworkComponents = () => {
     })
   }
 }
+
diff --git a/src/utils/markdown/processor.ts b/src/utils/markdown/processor.ts
index 484622b13..9ea90c858 100644
--- a/src/utils/markdown/processor.ts
+++ b/src/utils/markdown/processor.ts
@@ -13,14 +13,11 @@ import {
   rehypeParseCommentComponents,
   rehypeTransformCommentComponents,
   rehypeTransformFrameworkComponents,
+  type MarkdownHeading,
 } from '~/utils/markdown/plugins'
 import { extractCodeMeta } from '~/utils/markdown/plugins/extractCodeMeta'
 
-export type MarkdownHeading = {
-  id: string
-  text: string
-  level: number
-}
+export type { MarkdownHeading } from '~/utils/markdown/plugins'
 
 export type MarkdownRenderResult = {
   markup: string

From 867efe177e536464ff4c499fdcffe537d12a97a1 Mon Sep 17 00:00:00 2001
From: ladybluenotes <hello@sarahgerrard.me>
Date: Mon, 12 Jan 2026 10:36:13 -0800
Subject: [PATCH 2/3] fix: add padding to tab content when not only displaying
 a code block

---
 src/styles/app.css | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/styles/app.css b/src/styles/app.css
index 1addb3a72..d7eead6c4 100644
--- a/src/styles/app.css
+++ b/src/styles/app.css
@@ -981,3 +981,11 @@ mark {
 .framework-code-block > .codeblock {
   @apply my-4;
 }
+
+/* Tab content - add padding when it's not just a code block */
+[data-tab]:not(:has(> .codeblock:only-child)) {
+  @apply px-4;
+}
+
+
+

From 00e3026d940fc993a8386a8fc4901ef620f13377 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 12 Jan 2026 18:37:59 +0000
Subject: [PATCH 3/3] ci: apply automated fixes

---
 src/components/Doc.tsx                               |  6 +++++-
 src/components/Toc.tsx                               | 12 ++++++++++--
 src/styles/app.css                                   |  3 ---
 .../markdown/plugins/transformFrameworkComponent.ts  | 10 +++++++---
 4 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/src/components/Doc.tsx b/src/components/Doc.tsx
index c099efbb0..7ffc7c725 100644
--- a/src/components/Doc.tsx
+++ b/src/components/Doc.tsx
@@ -61,7 +61,11 @@ export function Doc({
   const { framework: paramsFramework } = useParams({ strict: false })
   const localCurrentFramework = useLocalCurrentFramework()
   const currentFramework = React.useMemo(() => {
-    const fw = frameworkProp || paramsFramework || localCurrentFramework.currentFramework || 'react'
+    const fw =
+      frameworkProp ||
+      paramsFramework ||
+      localCurrentFramework.currentFramework ||
+      'react'
     return typeof fw === 'string' ? fw.toLowerCase() : fw
   }, [frameworkProp, paramsFramework, localCurrentFramework.currentFramework])
 
diff --git a/src/components/Toc.tsx b/src/components/Toc.tsx
index 9f2e59669..7c23519db 100644
--- a/src/components/Toc.tsx
+++ b/src/components/Toc.tsx
@@ -21,13 +21,21 @@ type TocProps = {
   currentFramework?: string
 }
 
-export function Toc({ headings, textColor, activeHeadings, currentFramework }: TocProps) {
+export function Toc({
+  headings,
+  textColor,
+  activeHeadings,
+  currentFramework,
+}: TocProps) {
   // Filter headings based on framework scope
   const visibleHeadings = React.useMemo(() => {
     return headings.filter((heading) => {
       console.log(heading)
       if (heading.framework) {
-        return currentFramework && heading.framework === currentFramework.toLowerCase()
+        return (
+          currentFramework &&
+          heading.framework === currentFramework.toLowerCase()
+        )
       }
       // If no framework attribute, always show (not framework-scoped)
       return true
diff --git a/src/styles/app.css b/src/styles/app.css
index d7eead6c4..82d4eacb1 100644
--- a/src/styles/app.css
+++ b/src/styles/app.css
@@ -986,6 +986,3 @@ mark {
 [data-tab]:not(:has(> .codeblock:only-child)) {
   @apply px-4;
 }
-
-
-
diff --git a/src/utils/markdown/plugins/transformFrameworkComponent.ts b/src/utils/markdown/plugins/transformFrameworkComponent.ts
index 8d95c1eb3..38fdc7f35 100644
--- a/src/utils/markdown/plugins/transformFrameworkComponent.ts
+++ b/src/utils/markdown/plugins/transformFrameworkComponent.ts
@@ -85,7 +85,9 @@ function extractFrameworkData(node: HastNode): FrameworkExtraction | null {
   let firstFramework: string | null = null
   for (const child of children) {
     if (child.type === 'element' && child.tagName === 'h1') {
-      firstFramework = toString(child as any).trim().toLowerCase()
+      firstFramework = toString(child as any)
+        .trim()
+        .toLowerCase()
       break
     }
   }
@@ -130,7 +132,10 @@ function extractFrameworkData(node: HastNode): FrameworkExtraction | null {
       contentNode.tagName &&
       /^h[2-6]$/.test(contentNode.tagName)
     ) {
-      contentNode.properties = (contentNode.properties || {}) as Record<string, unknown>
+      contentNode.properties = (contentNode.properties || {}) as Record<
+        string,
+        unknown
+      >
       contentNode.properties['data-framework'] = currentFramework
     }
 
@@ -210,4 +215,3 @@ export const rehypeTransformFrameworkComponents = () => {
     })
   }
 }
-