specra 0.2.3 → 0.2.4

package/config/specra.config.schema.json

@@ -45,31 +45,26 @@
     },
     "BannerConfig": {
       "additionalProperties": false,
-      "description": "Site-wide banner configuration",
+      "description": "Banner configuration for version-level or site-level banners.   Site-wide banner configuration",
       "properties": {
-        "dismissible": {
-          "description": "Whether the banner can be dismissed",
-          "type": "boolean"
-        },
-        "enabled": {
-          "description": "Whether the banner is enabled",
-          "type": "boolean"
-        },
-        "message": {
-          "description": "Banner message",
+        "text": {
+          "description": "Banner message text. Supports markdown links like [text](/url).",
           "type": "string"
         },
         "type": {
-          "description": "Banner type",
+          "description": "Banner style: info, warning, error, success   Banner type",
           "enum": [
             "info",
             "warning",
-            "success",
-            "error"
+            "error",
+            "success"
           ],
           "type": "string"
         }
       },
+      "required": [
+        "text"
+      ],
       "type": "object"
     },
     "DeploymentConfig": {

package/dist/components/docs/Callout.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import {
     Info,
+    PenLine,
     AlertTriangle,
     CheckCircle2,
     XCircle,
@@ -33,10 +34,10 @@
       defaultTitle: 'Info',
     },
     note: {
-      icon: Info,
-      className: 'bg-blue-500/10 border-blue-500/30 text-blue-900 dark:bg-blue-400/5 dark:border-blue-500/20 dark:text-blue-400',
-      iconClassName: 'text-blue-600 dark:text-blue-400',
-      titleClassName: 'text-blue-700 dark:text-blue-300',
+      icon: PenLine,
+      className: 'bg-slate-500/10 border-slate-500/30 text-slate-900 dark:bg-slate-400/5 dark:border-slate-400/20 dark:text-slate-300',
+      iconClassName: 'text-slate-600 dark:text-slate-400',
+      titleClassName: 'text-slate-700 dark:text-slate-300',
       defaultTitle: 'Note',
     },
     warning: {

package/dist/components/docs/CodeBlock.svelte

@@ -114,8 +114,8 @@
   </div>
 
   <!-- Code content -->
-  <div class="bg-gray-200/50 dark:bg-[#0d1117] rounded-b-xl overflow-x-auto border border-border/50">
-    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = line.startsWith('-')}{@const isAddition = line.startsWith('+')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = tokenizeLine(line)}<div class="table-row {diffBgClass}"><span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span><span class="table-cell align-top">{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}</span></div>{/each}</code></pre>
+  <div class="bg-muted/30 dark:bg-muted/20 rounded-b-xl overflow-x-auto border border-border/50">
+    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = language === 'diff' && line.startsWith('-') && !line.startsWith('--')}{@const isAddition = language === 'diff' && line.startsWith('+') && !line.startsWith('++')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = tokenizeLine(line)}<div class="table-row {diffBgClass}"><span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span><span class="table-cell align-top">{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}</span></div>{/each}</code></pre>
   </div>
 </div>
 

package/dist/components/docs/DocLayout.svelte

@@ -66,7 +66,7 @@
 
   <DocMetadata {meta} {config} />
 
-  <div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:list-inside prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:list-inside prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground prose-strong:text-foreground prose-strong:font-semibold">
+  <div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground [&_ul_ul]:ps-4 [&_ul_ul]:mt-2 [&_ul_ul]:mb-0 [&_ol_ol]:ps-4 [&_ol_ol]:mt-2 [&_ol_ol]:mb-0 [&_ol_ul]:ps-4 [&_ol_ul]:mt-2 [&_ol_ul]:mb-0 [&_ul_ol]:ps-4 [&_ul_ol]:mt-2 [&_ul_ol]:mb-0 prose-strong:text-foreground prose-strong:font-semibold">
     {@render children()}
   </div>
 

package/dist/components/docs/Header.svelte

@@ -3,23 +3,63 @@
   import { getConfigContext } from '../../stores/config.js';
   import { sidebarStore } from '../../stores/sidebar.js';
   import VersionSwitcher from './VersionSwitcher.svelte';
+  import VersionBanner from './VersionBanner.svelte';
   import ThemeToggle from './ThemeToggle.svelte';
   import SearchModal from './SearchModal.svelte';
   import Logo from './Logo.svelte';
+  import Icon from './Icon.svelte';
   import type { SpecraConfig } from '../../config.types.js';
+  import type { BannerConfig } from '../../config.types.js';
+  import type { Snippet } from 'svelte';
+  import { browser } from '$app/environment';
+
+  interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+  }
 
   interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
+    versionBanner?: BannerConfig;
     config?: SpecraConfig;
+    subheader?: Snippet;
   }
 
-  let { currentVersion, versions, config: configProp }: Props = $props();
+  let { currentVersion, versions, versionsMeta, versionBanner, config: configProp, subheader }: Props = $props();
 
   const configStore = getConfigContext();
   let config = $derived(configProp || $configStore);
   let searchOpen = $state(false);
   let isFlush = $derived(config?.navigation?.sidebarStyle === 'flush');
+  let headerEl = $state<HTMLElement | null>(null);
+
+  // Set a CSS variable on :root with the header's actual height so sidebars
+  // can use it for their sticky top offset. Uses ResizeObserver to stay
+  // in sync when banner is dismissed or tabs change.
+  $effect(() => {
+    if (!browser || !headerEl) return;
+
+    function updateHeight() {
+      if (headerEl) {
+        const height = headerEl.offsetHeight;
+        document.documentElement.style.setProperty('--header-height', `${height}px`);
+      }
+    }
+
+    // Set immediately to avoid flash of wrong position
+    updateHeight();
+    // Also set on next frame in case layout hasn't settled
+    requestAnimationFrame(updateHeight);
+
+    const observer = new ResizeObserver(updateHeight);
+    observer.observe(headerEl);
+
+    return () => observer.disconnect();
+  });
 
   $effect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
@@ -33,7 +73,7 @@
   });
 </script>
 
-<header class="sticky top-0 z-50 w-full border-b border-border bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
+<header bind:this={headerEl} class="sticky top-0 z-50 w-full border-b border-border bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
   <div class="{isFlush ? '' : 'container mx-auto'} flex h-16 items-center justify-between px-4 md:px-6">
     <div class="flex items-center gap-1">
       <button
@@ -76,7 +116,7 @@
       {/if}
 
       {#if config.features?.versioning}
-        <VersionSwitcher {currentVersion} {versions} />
+        <VersionSwitcher {currentVersion} {versions} {versionsMeta} />
       {/if}
 
       <!-- Social Links -->
@@ -113,6 +153,28 @@
           <MessageCircle class="h-4 w-4" />
         </a>
       {/if}
+      {#if config.social?.custom}
+        {#each config.social.custom as link}
+          <span class="relative hidden md:inline-flex group/tip">
+            <a
+              href={link.url}
+              target="_blank"
+              rel="noopener noreferrer"
+              class="flex items-center justify-center h-9 w-9 rounded-md hover:bg-muted transition-colors"
+              aria-label={link.label}
+            >
+              {#if link.icon}
+                <Icon icon={link.icon} size={16} />
+              {:else}
+                <span class="text-xs font-medium">{link.label.slice(0, 2)}</span>
+              {/if}
+            </a>
+            <span class="absolute top-full left-1/2 -translate-x-1/2 mt-1 px-2 py-1 text-xs text-popover-foreground bg-popover border border-border rounded-md shadow-sm whitespace-nowrap pointer-events-none opacity-0 group-hover/tip:opacity-100 transition-opacity z-50">
+              {link.label}
+            </span>
+          </span>
+        {/each}
+      {/if}
 
       <ThemeToggle />
     </div>
@@ -120,4 +182,12 @@
 
   <!-- Search Modal -->
   <SearchModal isOpen={searchOpen} onClose={() => (searchOpen = false)} {config} />
+
+  {#if versionBanner}
+    <VersionBanner banner={versionBanner} />
+  {/if}
+
+  {#if subheader}
+    {@render subheader()}
+  {/if}
 </header>

package/dist/components/docs/Header.svelte.d.ts

@@ -1,8 +1,19 @@
 import type { SpecraConfig } from '../../config.types.js';
+import type { BannerConfig } from '../../config.types.js';
+import type { Snippet } from 'svelte';
+interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+}
 interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
+    versionBanner?: BannerConfig;
     config?: SpecraConfig;
+    subheader?: Snippet;
 }
 declare const Header: import("svelte").Component<Props, {}, "">;
 type Header = ReturnType<typeof Header>;

package/dist/components/docs/MdxLayout.svelte

@@ -11,6 +11,6 @@
   let { children }: { children?: import('svelte').Snippet } = $props()
 </script>
 
-<div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:list-inside prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:list-inside prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground prose-strong:text-foreground prose-strong:font-semibold">
+<div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground [&_ul_ul]:ps-4 [&_ul_ul]:mt-2 [&_ul_ul]:mb-0 [&_ol_ol]:ps-4 [&_ol_ol]:mt-2 [&_ol_ol]:mb-0 [&_ol_ul]:ps-4 [&_ol_ul]:mt-2 [&_ol_ul]:mb-0 [&_ul_ol]:ps-4 [&_ul_ol]:mt-2 [&_ul_ol]:mb-0 prose-strong:text-foreground prose-strong:font-semibold">
   {@render children?.()}
 </div>

package/dist/components/docs/MobileDocLayout.svelte

@@ -56,24 +56,12 @@
 </script>
 
 <div class="min-h-screen bg-background">
-  <!-- Header -->
+  <!-- Header (includes banner and tab groups via subheader snippet) -->
   {@render header()}
 
   <!-- Site-wide Banner -->
   <SiteBanner {config} />
 
-  <!-- Tab Groups - shown only if configured -->
-  {#if config.navigation?.tabGroups && config.navigation.tabGroups.length > 0}
-    <TabGroups
-      tabGroups={config.navigation.tabGroups}
-      activeTabId={activeTabGroup}
-      onTabChange={handleTabChange}
-      flush={isFlush}
-      {docs}
-      {version}
-    />
-  {/if}
-
   <!-- Mobile Sidebar Overlay -->
   {#if sidebarOpen}
     <div
@@ -179,7 +167,7 @@
       </main>
     </div>
   {:else}
-    <main class="container mx-auto px-2 md:px-6 py-8">
+    <main class="container mx-auto px-2 md:px-6">
       <div class="flex">
         <!-- Desktop Sidebar - inside container -->
         <div class="hidden lg:block">
@@ -191,7 +179,7 @@
           />
         </div>
 
-        <div class="flex-1 min-w-0">
+        <div class="flex-1 min-w-0 py-4">
           <div class="flex flex-col gap-2 px-2 md:px-8">
             <!-- Content -->
             {@render children()}

package/dist/components/docs/Sidebar.svelte

@@ -33,24 +33,17 @@
 
   let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
 
-  let hasTabGroups = $derived(
-    config.navigation?.tabGroups && config.navigation.tabGroups.length > 0
-  );
   let isFlush = $derived(config.navigation?.sidebarStyle === 'flush');
-  let stickyTop = $derived(hasTabGroups ? 'top-[7.5rem]' : 'top-24');
-  let maxHeight = $derived(
-    hasTabGroups ? 'max-h-[calc(100vh-10rem)]' : 'max-h-[calc(100vh-7rem)]'
-  );
   let containerClass = $derived(
     isFlush
-      ? `${maxHeight} overflow-y-auto p-4 border-r border-border`
-      : `${maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50`
+      ? `overflow-y-auto p-4 border-r border-border`
+      : `overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50`
   );
 </script>
 
 {#if config.navigation?.showSidebar}
-  <aside class="w-64 shrink-0 sticky {stickyTop} self-start">
-    <div class={containerClass}>
+  <aside class="w-64 shrink-0 sticky self-start pt-4" style="top: var(--header-height, 4rem);">
+    <div class={containerClass} style="max-height: calc(100vh - var(--header-height, 4rem) - 2rem);">
       <div class="flex items-center justify-between mb-4 px-2">
         <h2 class="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Documentation</h2>
         {#if config.features?.showVersionBadge && version}

package/dist/components/docs/SidebarMenuItems.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { page } from '$app/stores';
-  import { ChevronRight, ChevronDown, FolderOpen, Lock } from 'lucide-svelte';
+  import { ChevronRight, ChevronDown, Lock } from 'lucide-svelte';
   import type { SpecraConfig } from '../../config.types.js';
   import Icon from './Icon.svelte';
   import { sortSidebarItems, sortSidebarGroups } from '../../sidebar-utils.js';
@@ -260,8 +260,6 @@
       >
         {#if group.icon}
           <Icon icon={group.icon} size={16} className="shrink-0" />
-        {:else}
-          <FolderOpen size={16} class="shrink-0" />
         {/if}
         {group.label}
       </a>

package/dist/components/docs/TabGroups.svelte

@@ -111,8 +111,8 @@
       {/if}
     </div>
   {:else}
-    <!-- Full version with sticky header -->
-    <div class="sticky top-16 z-30 border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+    <!-- Full version -->
+    <div class="border-b border-border bg-muted/40 backdrop-blur supports-[backdrop-filter]:bg-muted/30">
       <div class="{flush ? '' : 'container mx-auto'} px-4 md:px-6">
         <!-- Mobile Dropdown -->
         <div class="md:hidden relative">

package/dist/components/docs/TableOfContents.svelte

@@ -16,14 +16,7 @@
   const maxDepth = $derived(config.navigation?.tocMaxDepth ?? 3);
   const filteredItems = $derived(items.filter((item) => item.level <= maxDepth));
 
-  // Check if tab groups are configured
-  const hasTabGroups = $derived(
-    config.navigation?.tabGroups != null && config.navigation.tabGroups.length > 0
-  );
-
-  // Adjust top position based on whether tabs are present
-  const stickyTop = $derived(hasTabGroups ? 'top-[7.5rem]' : 'top-24');
-  const maxHeight = $derived(hasTabGroups ? 'max-h-[calc(100vh-10rem)]' : 'max-h-[calc(100vh-7rem)]');
+  // Removed hardcoded top/max-height — now uses --header-height CSS variable set by Header
 
   $effect(() => {
     if (!browser || !showToc || filteredItems.length === 0) return;
@@ -79,8 +72,8 @@
 </script>
 
 {#if showToc && filteredItems.length > 0}
-  <aside class="w-64 hidden xl:block shrink-0 sticky {stickyTop} self-start">
-    <div class="{maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50">
+  <aside class="w-64 hidden xl:block shrink-0 sticky self-start pt-4" style="top: var(--header-height, 4rem);">
+    <div class="overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50" style="max-height: calc(100vh - var(--header-height, 4rem) - 2rem);">
       <h3 class="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-4 px-2">On this page</h3>
       <nav class="space-y-1">
         {#each filteredItems as item, index}

package/dist/components/docs/VersionBanner.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+  import { Info, AlertTriangle, XCircle, CheckCircle2, X } from 'lucide-svelte';
+
+  interface BannerConfig {
+    text: string;
+    type?: 'info' | 'warning' | 'error' | 'success';
+  }
+
+  interface Props {
+    banner: BannerConfig;
+  }
+
+  let { banner }: Props = $props();
+
+  let dismissed = $state(false);
+
+  const styles = {
+    info: {
+      bg: 'bg-blue-500/10 border-blue-500/30',
+      text: 'text-blue-900 dark:text-blue-300',
+      icon: Info,
+    },
+    warning: {
+      bg: 'bg-yellow-500/10 border-yellow-500/30',
+      text: 'text-yellow-900 dark:text-yellow-300',
+      icon: AlertTriangle,
+    },
+    error: {
+      bg: 'bg-red-500/10 border-red-500/30',
+      text: 'text-red-900 dark:text-red-300',
+      icon: XCircle,
+    },
+    success: {
+      bg: 'bg-green-500/10 border-green-500/30',
+      text: 'text-green-900 dark:text-green-300',
+      icon: CheckCircle2,
+    },
+  };
+
+  let style = $derived(styles[banner.type || 'info']);
+  let IconComponent = $derived(style.icon);
+</script>
+
+{#if !dismissed}
+  <div class="border-b {style.bg} {style.text}">
+    <div class="max-w-7xl mx-auto px-4 py-2.5 flex items-center justify-between gap-3">
+      <div class="flex items-center gap-2 text-sm">
+        <IconComponent class="h-4 w-4 shrink-0" />
+        <span>{banner.text}</span>
+      </div>
+      <button
+        onclick={() => dismissed = true}
+        class="shrink-0 p-0.5 rounded hover:bg-black/10 dark:hover:bg-white/10 transition-colors"
+        aria-label="Dismiss banner"
+      >
+        <X class="h-3.5 w-3.5" />
+      </button>
+    </div>
+  </div>
+{/if}

package/dist/components/docs/VersionBanner.svelte.d.ts

@@ -0,0 +1,10 @@
+interface BannerConfig {
+    text: string;
+    type?: 'info' | 'warning' | 'error' | 'success';
+}
+interface Props {
+    banner: BannerConfig;
+}
+declare const VersionBanner: import("svelte").Component<Props, {}, "">;
+type VersionBanner = ReturnType<typeof VersionBanner>;
+export default VersionBanner;

package/dist/components/docs/VersionSwitcher.svelte

@@ -4,16 +4,38 @@
   import { page } from '$app/stores';
   import { browser } from '$app/environment';
 
+  interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+  }
+
   interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
   }
 
-  let { currentVersion, versions }: Props = $props();
+  let { currentVersion, versions, versionsMeta }: Props = $props();
 
   let isOpen = $state(false);
   let dropdownEl = $state<HTMLDivElement | null>(null);
 
+  // Build version list: use metadata if available, filter hidden versions
+  let visibleVersions = $derived.by(() => {
+    if (versionsMeta && versionsMeta.length > 0) {
+      return versionsMeta.filter(v => !v.hidden);
+    }
+    return versions.map(id => ({ id, label: id }));
+  });
+
+  // Get current version display label
+  let currentLabel = $derived.by(() => {
+    const meta = versionsMeta?.find(v => v.id === currentVersion);
+    return meta?.label || currentVersion;
+  });
+
   $effect(() => {
     if (!browser || !isOpen) return;
 
@@ -38,8 +60,8 @@
     };
   });
 
-  function switchVersion(version: string) {
-    if (version === currentVersion) {
+  function switchVersion(versionId: string) {
+    if (versionId === currentVersion) {
       isOpen = false;
       return;
     }
@@ -47,7 +69,7 @@
     const currentPath = $page.url.pathname;
     const newPath = currentPath.replace(
       new RegExp(`/${currentVersion}(/|$)`),
-      `/${version}$1`
+      `/${versionId}$1`
     );
 
     isOpen = false;
@@ -55,7 +77,7 @@
   }
 </script>
 
-{#if versions.length > 1}
+{#if visibleVersions.length > 1}
   <div class="relative" bind:this={dropdownEl}>
     <button
       onclick={() => (isOpen = !isOpen)}
@@ -64,27 +86,32 @@
       aria-haspopup="listbox"
       aria-label="Switch version"
     >
-      <span>{currentVersion}</span>
+      <span>{currentLabel}</span>
       <ChevronDown class="h-3.5 w-3.5 text-muted-foreground transition-transform {isOpen ? 'rotate-180' : ''}" />
     </button>
 
     {#if isOpen}
       <div
-        class="absolute top-full right-0 mt-1 w-40 py-1 bg-popover border border-border rounded-md shadow-lg z-50"
+        class="absolute top-full right-0 mt-1 w-48 py-1 bg-popover border border-border rounded-md shadow-lg z-50"
         role="listbox"
         aria-label="Available versions"
       >
-        {#each versions as version}
+        {#each visibleVersions as version}
           <button
             role="option"
-            aria-selected={version === currentVersion}
-            onclick={() => switchVersion(version)}
-            class="w-full flex items-center justify-between px-3 py-1.5 text-sm transition-colors {version === currentVersion
+            aria-selected={version.id === currentVersion}
+            onclick={() => switchVersion(version.id)}
+            class="w-full flex items-center justify-between px-3 py-1.5 text-sm transition-colors {version.id === currentVersion
               ? 'text-primary bg-accent/50 font-medium'
               : 'text-foreground hover:bg-accent'}"
           >
-            <span>{version}</span>
-            {#if version === currentVersion}
+            <span class="flex items-center gap-2">
+              {version.label}
+              {#if version.badge}
+                <span class="px-1.5 py-0.5 text-[10px] font-medium rounded-full bg-primary/10 text-primary leading-none">{version.badge}</span>
+              {/if}
+            </span>
+            {#if version.id === currentVersion}
               <Check class="h-3.5 w-3.5 text-primary" />
             {/if}
           </button>

package/dist/components/docs/VersionSwitcher.svelte.d.ts

@@ -1,6 +1,13 @@
+interface VersionMeta {
+    id: string;
+    label: string;
+    badge?: string;
+    hidden?: boolean;
+}
 interface Props {
     currentVersion: string;
     versions: string[];
+    versionsMeta?: VersionMeta[];
 }
 declare const VersionSwitcher: import("svelte").Component<Props, {}, "">;
 type VersionSwitcher = ReturnType<typeof VersionSwitcher>;

package/dist/components/docs/index.d.ts

@@ -51,6 +51,7 @@ export { default as TimelineItem } from './TimelineItem.svelte';
 export { default as Tabs } from './Tabs.svelte';
 export { default as ThemeToggle } from './ThemeToggle.svelte';
 export { default as Tooltip } from './Tooltip.svelte';
+export { default as VersionBanner } from './VersionBanner.svelte';
 export { default as VersionSwitcher } from './VersionSwitcher.svelte';
 export { default as Video } from './Video.svelte';
 export { ApiEndpoint, ApiParams, ApiResponse, ApiResponseDisplay, ApiPlayground, ApiReference, } from './api/index.js';

package/dist/components/docs/index.js

@@ -52,6 +52,7 @@ export { default as TimelineItem } from './TimelineItem.svelte';
 export { default as Tabs } from './Tabs.svelte';
 export { default as ThemeToggle } from './ThemeToggle.svelte';
 export { default as Tooltip } from './Tooltip.svelte';
+export { default as VersionBanner } from './VersionBanner.svelte';
 export { default as VersionSwitcher } from './VersionSwitcher.svelte';
 export { default as Video } from './Video.svelte';
 // API components

package/dist/config.d.ts

@@ -4,5 +4,5 @@
  * The actual config loading happens on the server and is passed as props
  */
 export { defaultConfig } from "./config.types";
-export type { SpecraConfig } from "./config.types";
+export type { SpecraConfig, VersionConfig, BannerConfig } from "./config.types";
 export { getConfig, getConfigValue, loadConfig, processContentWithEnv, replaceEnvVariables, validateConfig, reloadConfig, } from "./config.server";

package/dist/config.server.d.ts

@@ -1,4 +1,4 @@
-import type { SpecraConfig } from "./config.types";
+import type { SpecraConfig, VersionConfig } from "./config.types";
 /**
  * Load and parse the Specra configuration file
  * Falls back to default configuration if file doesn't exist or is invalid
@@ -41,6 +41,33 @@ export declare function getConfig(): SpecraConfig;
  * Reload the configuration (useful for development) (SERVER ONLY)
  */
 export declare function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+export declare function loadVersionConfig(version: string): VersionConfig | null;
+/**
+ * Get the effective config for a specific version.
+ * Merges global config with per-version overrides from _version_.json.
+ * If no _version_.json exists, returns the global config unchanged.
+ */
+export declare function getEffectiveConfig(version: string): SpecraConfig;
+/**
+ * Version metadata for display in the version switcher.
+ */
+export interface VersionMeta {
+    /** Directory name (e.g., "v1.0.0") — used for routing */
+    id: string;
+    /** Display label (e.g., "v1.0 (Stable)") — defaults to id */
+    label: string;
+    /** Short badge text (e.g., "Beta", "LTS") */
+    badge?: string;
+    /** Whether this version is hidden from the switcher */
+    hidden?: boolean;
+    /** Version-level banner */
+    banner?: import("./config.types").BannerConfig;
+}
+/**
+ * Get metadata for all versions, enriched with _version_.json data.
+ * Hidden versions are included but marked — the UI decides whether to show them.
+ */
+export declare function getVersionsMeta(versions: string[]): VersionMeta[];
 /**
  * Export the loaded config as default (SERVER ONLY)
  */

package/dist/config.server.js

@@ -1,3 +1,5 @@
+import fs from "fs";
+import path from "path";
 import { defaultConfig } from "./config.types";
 /**
  * Deep merge two objects
@@ -143,6 +145,70 @@ export function reloadConfig(userConfig) {
     configInstance = loadConfig(userConfig);
     return configInstance;
 }
+/**
+ * Load per-version configuration from docs/{version}/_version_.json.
+ * Returns null if the file doesn't exist or is invalid.
+ */
+const versionConfigCache = new Map();
+const VCFG_TTL = process.env.NODE_ENV === 'development' ? 5000 : 60000;
+export function loadVersionConfig(version) {
+    const cached = versionConfigCache.get(version);
+    if (cached && Date.now() - cached.timestamp < VCFG_TTL) {
+        return cached.data;
+    }
+    try {
+        const versionConfigPath = path.join(process.cwd(), "docs", version, "_version_.json");
+        if (!fs.existsSync(versionConfigPath)) {
+            versionConfigCache.set(version, { data: null, timestamp: Date.now() });
+            return null;
+        }
+        const content = fs.readFileSync(versionConfigPath, "utf8");
+        const data = JSON.parse(content);
+        versionConfigCache.set(version, { data, timestamp: Date.now() });
+        return data;
+    }
+    catch (error) {
+        console.error(`Error loading _version_.json for ${version}:`, error);
+        versionConfigCache.set(version, { data: null, timestamp: Date.now() });
+        return null;
+    }
+}
+/**
+ * Get the effective config for a specific version.
+ * Merges global config with per-version overrides from _version_.json.
+ * If no _version_.json exists, returns the global config unchanged.
+ */
+export function getEffectiveConfig(version) {
+    const globalConfig = getConfig();
+    const versionConfig = loadVersionConfig(version);
+    if (!versionConfig) {
+        return globalConfig;
+    }
+    const effective = { ...globalConfig };
+    if (versionConfig.tabGroups !== undefined) {
+        effective.navigation = {
+            ...effective.navigation,
+            tabGroups: versionConfig.tabGroups,
+        };
+    }
+    return effective;
+}
+/**
+ * Get metadata for all versions, enriched with _version_.json data.
+ * Hidden versions are included but marked — the UI decides whether to show them.
+ */
+export function getVersionsMeta(versions) {
+    return versions.map(id => {
+        const versionConfig = loadVersionConfig(id);
+        return {
+            id,
+            label: versionConfig?.label || id,
+            badge: versionConfig?.badge,
+            hidden: versionConfig?.hidden,
+            banner: versionConfig?.banner,
+        };
+    });
+}
 /**
  * Export the loaded config as default (SERVER ONLY)
  */

package/dist/config.types.d.ts

@@ -59,6 +59,31 @@ export interface TabGroup {
     /** Optional icon name (lucide-react icon) */
     icon?: string;
 }
+/**
+ * Banner configuration for version-level or site-level banners.
+ */
+export interface BannerConfig {
+    /** Banner message text. Supports markdown links like [text](/url). */
+    text: string;
+    /** Banner style: info, warning, error, success */
+    type?: 'info' | 'warning' | 'error' | 'success';
+}
+/**
+ * Per-version configuration that can override global config settings.
+ * Loaded from docs/{version}/_version_.json
+ */
+export interface VersionConfig {
+    /** Display label for this version (e.g., "v1.0 (Stable)"). Defaults to directory name. */
+    label?: string;
+    /** Hide this version from the version switcher. Useful for unreleased versions. */
+    hidden?: boolean;
+    /** Short badge text shown next to the version (e.g., "Beta", "LTS", "Deprecated"). */
+    badge?: string;
+    /** Banner shown at the top of every page in this version. Overrides global banner. */
+    banner?: BannerConfig;
+    /** Override tab groups for this version. Empty array = no tabs. */
+    tabGroups?: TabGroup[];
+}
 /**
  * Navigation and sidebar configuration
  */

package/dist/mdx.js

@@ -81,28 +81,34 @@ const PROP_NAME_MAP = {
  *   span={2}                  →  span="__jsx:2"
  *   variant="success"         →  (unchanged, already a string)
  */
-function preprocessJsxExpressions(markdown) {
-    // Split markdown into fenced code blocks and non-code segments.
-    // Only process JSX expressions in non-code segments to avoid corrupting code examples.
-    // Matches ```` ``` ```` or ```` ```` ```` fenced blocks (3+ backticks or tildes).
+/**
+ * Split markdown into fenced code blocks and non-code segments.
+ * Code blocks are preserved as-is; only non-code segments should be
+ * processed by JSX/component preprocessing functions.
+ * Matches 3+ backticks or tildes as fence markers.
+ */
+function splitByCodeFences(markdown) {
     const fencedCodeRegex = /(^|\n)((`{3,}|~{3,}).*\n[\s\S]*?\n\3\s*(?:\n|$))/g;
     const segments = [];
     let lastIndex = 0;
     let match;
     while ((match = fencedCodeRegex.exec(markdown)) !== null) {
         const codeStart = match.index + (match[1]?.length || 0);
-        // Add the non-code segment before this code block
         if (codeStart > lastIndex) {
             segments.push({ text: markdown.slice(lastIndex, codeStart), isCode: false });
         }
-        // Add the code block as-is
         segments.push({ text: match[2], isCode: true });
         lastIndex = match.index + match[0].length;
     }
-    // Add remaining non-code segment
     if (lastIndex < markdown.length) {
         segments.push({ text: markdown.slice(lastIndex), isCode: false });
     }
+    return segments;
+}
+function preprocessJsxExpressions(markdown) {
+    // Split markdown into fenced code blocks and non-code segments.
+    // Only process JSX expressions in non-code segments to avoid corrupting code examples.
+    const segments = splitByCodeFences(markdown);
     // Build a pattern that matches known component tag names (case-insensitive for safety)
     const allNames = [...new Set([
             ...Object.values(COMPONENT_TAG_MAP),
@@ -425,9 +431,7 @@ function extractCodeBlockProps(node) {
     // Extract language from className like ['language-javascript']
     const classNames = codeChild.properties?.className || [];
     const langClass = classNames.find((c) => typeof c === 'string' && c.startsWith('language-'));
-    if (!langClass)
-        return null;
-    const language = langClass.replace('language-', '');
+    const language = langClass ? langClass.replace('language-', '') : 'txt';
     // Extract text content from the code element
     const code = extractTextContent(codeChild).replace(/\n$/, '');
     // Check for filename in data attributes (e.g. from remark-code-meta)
@@ -463,6 +467,7 @@ function childrenContainMarkdownText(children) {
                 /\[.*\]\(/.test(text) || // links
                 /(?:^|\n)\s*[-*+]\s/.test(child.value) || // unordered lists
                 /(?:^|\n)\s*\d+\.\s/.test(child.value) || // ordered lists
+                /(?:^|\n)\s*(`{3,}|~{3,})/.test(child.value) || // fenced code blocks
                 (text.length > 10 && /\n/.test(text.trim())) // multi-line text content (paragraphs)
             ) {
                 return true;
@@ -493,9 +498,72 @@ function dedent(text) {
     // Strip the common indent from all lines
     return lines.map(line => line.slice(minIndent)).join('\n');
 }
+/**
+ * Check if a text buffer currently has an unclosed fenced code block.
+ * Returns the fence marker (e.g. "```") if inside a code fence, or null otherwise.
+ */
+function getOpenCodeFence(text) {
+    const lines = text.split('\n');
+    let openFence = null;
+    for (const line of lines) {
+        if (openFence) {
+            // Check if this line closes the fence (same or more chars of same type)
+            const trimmed = line.trim();
+            if (trimmed.startsWith(openFence) && /^(`{3,}|~{3,})\s*$/.test(trimmed)) {
+                openFence = null;
+            }
+        }
+        else {
+            // Check if this line opens a fence
+            const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+            if (fenceMatch) {
+                openFence = fenceMatch[1];
+            }
+        }
+    }
+    return openFence;
+}
+/**
+ * Serialize a hast element back to its original tag text representation.
+ * Used to reconstruct component/element tags as plain text when they
+ * appear inside fenced code blocks (where they should be code, not components).
+ */
+function hastElementToText(node) {
+    const tagName = node.tagName || 'div';
+    // Restore PascalCase for known components
+    const displayName = COMPONENT_TAG_MAP[tagName] || tagName;
+    const props = node.properties || {};
+    const attrs = Object.entries(props)
+        .filter(([key]) => key !== 'className' || props[key]?.length > 0)
+        .map(([key, value]) => {
+        if (value === true || value === '')
+            return key;
+        if (typeof value === 'string' && value.startsWith('__jsx:')) {
+            // Restore JSX expression syntax
+            const expr = value.slice(6).replace(/&quot;/g, '"').replace(/&#10;/g, '\n');
+            return `${key}={${expr}}`;
+        }
+        return `${key}="${value}"`;
+    })
+        .join(' ');
+    const openTag = attrs ? `<${displayName} ${attrs}>` : `<${displayName}>`;
+    const childText = (node.children || []).map((c) => {
+        if (c.type === 'text')
+            return c.value || '';
+        if (c.type === 'element')
+            return hastElementToText(c);
+        return '';
+    }).join('');
+    return `${openTag}${childText}</${displayName}>`;
+}
 /**
  * Extract raw text from hast children, preserving component tags as placeholders.
  * Returns the markdown text and a map of placeholders to component MdxNodes.
+ *
+ * Tracks open code fences in the text buffer: if the buffer contains an unclosed
+ * fenced code block (e.g. ``` opened but not closed), subsequent component/element
+ * children are serialized back to text instead of being processed as real components.
+ * This prevents component tags inside code examples from rendering as live components.
  */
 async function processComponentChildren(children) {
     // Separate text runs from component/element children.
@@ -530,42 +598,52 @@ async function processComponentChildren(children) {
         if (child.type === 'text') {
             textBuffer += child.value || '';
         }
-        else if (isComponentElement(child)) {
-            await flushTextBuffer();
-            const componentName = COMPONENT_TAG_MAP[child.tagName];
-            const props = convertProps(child.properties || {});
-            const childNodes = child.children && child.children.length > 0
-                ? await processSmartChildren(child.children)
-                : [];
-            result.push({
-                type: 'component',
-                name: componentName,
-                props,
-                children: childNodes,
-            });
-        }
-        else if (child.type === 'element') {
-            // Regular HTML element inside a component — flush text first, then serialize
-            await flushTextBuffer();
-            const codeBlockProps = extractCodeBlockProps(child);
-            if (codeBlockProps) {
+        else if (isComponentElement(child) || child.type === 'element') {
+            // Check if we're inside an unclosed code fence in the text buffer.
+            // If so, this element is part of a code example — serialize it back
+            // to text rather than processing it as a real component.
+            const openFence = getOpenCodeFence(textBuffer);
+            if (openFence) {
+                // We're inside a code fence — serialize this element as text
+                textBuffer += hastElementToText(child);
+            }
+            else if (isComponentElement(child)) {
+                await flushTextBuffer();
+                const componentName = COMPONENT_TAG_MAP[child.tagName];
+                const props = convertProps(child.properties || {});
+                const childNodes = child.children && child.children.length > 0
+                    ? await processSmartChildren(child.children)
+                    : [];
                 result.push({
                     type: 'component',
-                    name: 'CodeBlock',
-                    props: codeBlockProps,
-                    children: [],
+                    name: componentName,
+                    props,
+                    children: childNodes,
                 });
             }
-            else if (hasNestedComponent(child)) {
-                const openTag = toHtml({ ...child, children: [] }).replace(/<\/[^>]+>$/, '');
-                result.push({ type: 'html', content: openTag });
-                result.push(...await processSmartChildren(child.children));
-                result.push({ type: 'html', content: `</${child.tagName}>` });
-            }
             else {
-                const html = toHtml(child).trim();
-                if (html) {
-                    result.push({ type: 'html', content: html });
+                // Regular HTML element inside a component — flush text first, then serialize
+                await flushTextBuffer();
+                const codeBlockProps = extractCodeBlockProps(child);
+                if (codeBlockProps) {
+                    result.push({
+                        type: 'component',
+                        name: 'CodeBlock',
+                        props: codeBlockProps,
+                        children: [],
+                    });
+                }
+                else if (hasNestedComponent(child)) {
+                    const openTag = toHtml({ ...child, children: [] }).replace(/<\/[^>]+>$/, '');
+                    result.push({ type: 'html', content: openTag });
+                    result.push(...await processSmartChildren(child.children));
+                    result.push({ type: 'html', content: `</${child.tagName}>` });
+                }
+                else {
+                    const html = toHtml(child).trim();
+                    if (html) {
+                        result.push({ type: 'html', content: html });
+                    }
                 }
             }
         }
@@ -672,9 +750,214 @@ function hasNestedComponent(node) {
  * Runs the same remark/rehype pipeline but produces an AST
  * instead of a stringified HTML output.
  */
+/**
+ * Dedent content inside component tags before remark processing.
+ * In CommonMark, 4+ spaces of indentation create code blocks.
+ * When users indent content inside component tags (e.g. <Tabs> inside <Step>),
+ * the inherited indentation causes remark to misinterpret child tags and
+ * markdown as indented code blocks. This strips common leading indentation
+ * from the content between known component open/close tags.
+ *
+ * Only processes the outermost component tags (those not nested inside another
+ * known component). Inner components are handled naturally since their parent's
+ * dedent removes the shared indentation.
+ */
+/**
+ * Identify which lines in a text block are inside fenced code blocks.
+ * Returns a Set of line indices (0-based) that are inside code fences.
+ */
+function getCodeFenceLineIndices(lines) {
+    const indices = new Set();
+    let openFence = null;
+    let openIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (openFence) {
+            indices.add(i);
+            const trimmed = line.trim();
+            if (trimmed.startsWith(openFence) && new RegExp(`^${openFence[0]}{${openFence.length},}\\s*$`).test(trimmed)) {
+                openFence = null;
+            }
+        }
+        else {
+            const fenceMatch = line.match(/^(\s*)(`{3,}|~{3,})/);
+            if (fenceMatch) {
+                openFence = fenceMatch[2];
+                openIndex = i;
+                indices.add(i);
+            }
+        }
+    }
+    return indices;
+}
+function dedentComponentChildren(markdown) {
+    // Build a single regex that matches any known component opening tag
+    const allNames = [...new Set([
+            ...Object.values(COMPONENT_TAG_MAP),
+            ...Object.keys(COMPONENT_TAG_MAP),
+        ])];
+    const namesPattern = allNames.join('|');
+    // Find outermost component blocks and dedent their entire content
+    // (including nested component tags) so remark doesn't misinterpret indentation.
+    const openTagRegex = new RegExp(`(<(?:${namesPattern})(?:\\s[^>]*)?>)(\\n)`, 'gi');
+    let result = '';
+    let lastIndex = 0;
+    let match;
+    openTagRegex.lastIndex = 0;
+    while ((match = openTagRegex.exec(markdown)) !== null) {
+        // Skip if this tag is nested inside a previously processed block
+        if (match.index < lastIndex)
+            continue;
+        const tagName = match[1].match(/<(\w+)/)?.[1];
+        if (!tagName)
+            continue;
+        const contentStart = match.index + match[0].length;
+        // Find the matching closing tag, handling nesting of the SAME tag
+        const closeTagRegex = new RegExp(`</${tagName}\\s*>`, 'gi');
+        const openNestRegex = new RegExp(`<${tagName}(?:\\s[^>]*)?>`, 'gi');
+        closeTagRegex.lastIndex = contentStart;
+        openNestRegex.lastIndex = contentStart;
+        let depth = 1;
+        let closeMatch = null;
+        while (depth > 0 && (closeMatch = closeTagRegex.exec(markdown)) !== null) {
+            // Count any nested opens of the same tag before this close
+            while (true) {
+                const nested = openNestRegex.exec(markdown);
+                if (!nested || nested.index >= closeMatch.index) {
+                    openNestRegex.lastIndex = closeMatch.index + closeMatch[0].length;
+                    break;
+                }
+                depth++;
+            }
+            depth--;
+        }
+        if (!closeMatch)
+            continue;
+        const contentEnd = closeMatch.index;
+        const innerContent = markdown.slice(contentStart, contentEnd);
+        // Find minimum indentation of non-empty lines that are NOT inside code fences.
+        // Lines inside code fences (including fence markers and their content) are
+        // excluded so that code at indent 0 doesn't prevent dedenting of component content.
+        const lines = innerContent.split('\n');
+        const codeFenceLines = getCodeFenceLineIndices(lines);
+        let minIndent = Infinity;
+        for (let i = 0; i < lines.length; i++) {
+            if (codeFenceLines.has(i))
+                continue;
+            const line = lines[i];
+            if (line.trim().length === 0)
+                continue;
+            const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+            if (indent > 0 && indent < minIndent)
+                minIndent = indent;
+        }
+        if (minIndent > 0 && minIndent !== Infinity) {
+            // Dedent non-code-fence lines by the common indent.
+            // Code fence lines are left as-is to preserve their content.
+            const dedented = lines.map((line, i) => {
+                if (codeFenceLines.has(i))
+                    return line;
+                if (line.trim().length === 0)
+                    return line;
+                return line.slice(Math.min(minIndent, line.match(/^(\s*)/)?.[1].length ?? 0));
+            }).join('\n');
+            result += markdown.slice(lastIndex, contentStart) + dedented;
+            lastIndex = contentEnd;
+            // Advance past this entire component block
+            openTagRegex.lastIndex = closeMatch.index + closeMatch[0].length;
+        }
+    }
+    if (lastIndex > 0) {
+        result += markdown.slice(lastIndex);
+        markdown = result;
+        // Re-run to handle inner components that were previously skipped
+        // (e.g. <Step> inside <Steps> now has reduced indentation that needs further dedenting)
+        return dedentComponentChildren(markdown);
+    }
+    return markdown;
+}
+/**
+ * Collapse blank lines inside component blocks so remark-parse treats the
+ * entire component (from opening to closing tag) as a single HTML block.
+ *
+ * In CommonMark, a blank line inside an HTML block (type 6) ends the block.
+ * This causes remark to split component content into separate blocks, and
+ * plain text between child components becomes a `<p>` element that disrupts
+ * parse5's handling of unknown element nesting (siblings become children).
+ *
+ * By removing blank lines inside component blocks, the entire component tree
+ * stays as one HTML block that parse5 can parse correctly.
+ */
+function ensureComponentBlockIntegrity(markdown) {
+    const allNames = [...new Set([
+            ...Object.values(COMPONENT_TAG_MAP),
+            ...Object.keys(COMPONENT_TAG_MAP),
+        ])];
+    const namesPattern = allNames.join('|');
+    // Find outermost component blocks and collapse blank lines within them
+    const openTagRegex = new RegExp(`^(\\s*<(?:${namesPattern})(?:\\s[^>]*)?>)\\s*$`, 'gim');
+    let result = '';
+    let lastIndex = 0;
+    let match;
+    openTagRegex.lastIndex = 0;
+    while ((match = openTagRegex.exec(markdown)) !== null) {
+        // Skip if inside a previously processed block
+        if (match.index < lastIndex)
+            continue;
+        const tagName = match[1].match(/<(\w+)/)?.[1];
+        if (!tagName)
+            continue;
+        const blockStart = match.index;
+        // Find matching closing tag, handling nesting
+        const closeTagRegex = new RegExp(`</${tagName}\\s*>`, 'gi');
+        const openNestRegex = new RegExp(`<${tagName}(?:\\s[^>]*)?>`, 'gi');
+        closeTagRegex.lastIndex = match.index + match[0].length;
+        openNestRegex.lastIndex = match.index + match[0].length;
+        let depth = 1;
+        let closeMatch = null;
+        while (depth > 0 && (closeMatch = closeTagRegex.exec(markdown)) !== null) {
+            while (true) {
+                const nested = openNestRegex.exec(markdown);
+                if (!nested || nested.index >= closeMatch.index) {
+                    openNestRegex.lastIndex = closeMatch.index + closeMatch[0].length;
+                    break;
+                }
+                depth++;
+            }
+            depth--;
+        }
+        if (!closeMatch)
+            continue;
+        const blockEnd = closeMatch.index + closeMatch[0].length;
+        const block = markdown.slice(blockStart, blockEnd);
+        // Replace blank/whitespace-only lines (outside code fences) with HTML
+        // comments so remark doesn't end the HTML block at those points.
+        // In CommonMark, a blank line inside an HTML type-6 block ends the block.
+        // An HTML comment on the line prevents this while being invisible in output.
+        // Replace ALL blank/whitespace-only lines with HTML comments — even inside
+        // code fences. The code fence content is raw text inside the HTML block and
+        // will be re-processed by processComponentChildren through the markdown
+        // pipeline, which restores proper code formatting.
+        const collapsed = block.replace(/^\s*$/gm, '<!-- -->');
+        result += markdown.slice(lastIndex, blockStart) + collapsed;
+        lastIndex = blockEnd;
+        openTagRegex.lastIndex = blockEnd;
+    }
+    if (lastIndex > 0) {
+        result += markdown.slice(lastIndex);
+        return result;
+    }
+    return markdown;
+}
 async function processMarkdownToMdxNodes(markdown) {
     // Pre-process JSX expression attributes into HTML-safe string attributes
     const preprocessed = preprocessJsxExpressions(markdown);
+    // Dedent content inside component tags so that indented children
+    // (e.g. <Tabs> inside <Step>) don't get treated as code blocks
+    // by remark-parse (4+ spaces = indented code in CommonMark).
+    const dedented = dedentComponentChildren(preprocessed);
+    // Ensure component block integrity in the markdown
+    const normalized = ensureComponentBlockIntegrity(dedented);
     const processor = unified()
         .use(remarkParse)
         .use(remarkGfm)
@@ -683,7 +966,7 @@ async function processMarkdownToMdxNodes(markdown) {
         .use(rehypeRaw)
         .use(rehypeSlug)
         .use(rehypeKatex);
-    const mdast = processor.parse(preprocessed);
+    const mdast = processor.parse(normalized);
     const hast = await processor.run(mdast);
     // The hast root has children - process them into MdxNodes
     const children = hast.children || [];

package/dist/styles/globals.css

@@ -147,6 +147,8 @@
     scroll-behavior: smooth;
     /* Always reserve space for scrollbar to prevent layout shift */
     scrollbar-gutter: stable;
+    /* Default header height — updated dynamically by Header component's ResizeObserver */
+    --header-height: 4rem;
   }
 
   body {
@@ -420,6 +422,75 @@ pre code {
   margin-bottom: 0.75rem;
 }
 
+/* Override Tailwind typography's padding-inline-start on lists.
+   The plugin applies ~1.625em to every ol/ul, which compounds on
+   nested lists — each level pushes content further right.
+   Top-level lists get a modest indent; nested lists get less. */
+.prose :where(ol, ul):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  padding-inline-start: 1.25em;
+}
+
+.prose :where(li ol, li ul):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  padding-inline-start: 1em;
+}
+
+/* Table styles - bordered with rounded corners matching CodeBlock/Callout */
+.prose :where(table):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid var(--border);
+  border-radius: 0.75rem;
+  overflow: hidden;
+  width: 100%;
+  margin-top: 1rem;
+  margin-bottom: 1rem;
+  display: block;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.prose :where(thead):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  background: var(--muted);
+}
+
+.prose :where(thead th):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  border-bottom: 1px solid var(--border);
+  border-right: 1px solid var(--border);
+  padding: 0.625rem 1rem;
+  font-weight: 600;
+  font-size: 0.875rem;
+  text-align: left;
+  color: var(--foreground);
+}
+
+.prose :where(thead th:last-child):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  border-right: none;
+}
+
+.prose :where(tbody td):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  border-bottom: 1px solid var(--border);
+  border-right: 1px solid var(--border);
+  padding: 0.625rem 1rem;
+  font-size: 0.875rem;
+  color: var(--muted-foreground);
+}
+
+.prose :where(tbody td:last-child):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  border-right: none;
+}
+
+.prose :where(tbody tr:last-child td):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  border-bottom: none;
+}
+
+.prose :where(tbody tr:hover):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  background: var(--muted);
+}
+
+.dark .prose :where(tbody tr:hover):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
+  background: var(--muted);
+}
+
 html body[data-scroll-locked] {
   overflow: visible !important;
   margin-right: 0 !important;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "A modern documentation library for SvelteKit with built-in versioning, API reference generation, full-text search, and MDX support",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",