specra 0.2.2 → 0.2.4

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/componentTextProps.js

@@ -24,6 +24,8 @@ export const COMPONENT_TEXT_PROPS = {
     CodeBlock: ["filename"],
     // Step components
     Step: ["title"],
+    // Timeline components
+    TimelineItem: ["title", "date"],
 };
 export function extractComponentPropsText(mdx) {
     return mdx.replace(/<([A-Z][\w]*)\b([^/>]*)\/>/g, (_, component, props) => {

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

@@ -46,9 +46,12 @@ export { default as Steps } from './Steps.svelte';
 export { default as Tab } from './Tab.svelte';
 export { default as TabGroups } from './TabGroups.svelte';
 export { default as TableOfContents } from './TableOfContents.svelte';
+export { default as Timeline } from './Timeline.svelte';
+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

@@ -47,9 +47,12 @@ export { default as Steps } from './Steps.svelte';
 export { default as Tab } from './Tab.svelte';
 export { default as TabGroups } from './TabGroups.svelte';
 export { default as TableOfContents } from './TableOfContents.svelte';
+export { default as Timeline } from './Timeline.svelte';
+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-components.js

@@ -13,9 +13,9 @@
  * <Callout type="info">This is a callout</Callout>
  * ```
  */
-import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, } from './components/docs';
+import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, } from './components/docs';
 // Re-export all MDX-usable components
-export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, };
+export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, };
 /**
  * Component map for passing to layout components that render MDX content.
  */
@@ -43,6 +43,8 @@ export const mdxComponents = {
     Tooltip,
     Frame,
     CodeBlock,
+    Timeline,
+    TimelineItem,
     ApiEndpoint,
     ApiParams,
     ApiResponse,

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 || [];