npm - specra - Versions diffs - 0.2.51 → 0.2.55 - Mend

specra 0.2.51 → 0.2.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/config/rehype-base-path.d.ts +1 -0
package/config/svelte-config.js +95 -6
package/dist/components/docs/Breadcrumb.svelte +3 -2
package/dist/components/docs/CategoryIndex.svelte +5 -4
package/dist/components/docs/DocNavigation.svelte +3 -2
package/dist/components/docs/Footer.svelte +10 -1
package/dist/components/docs/Header.svelte +19 -3
package/dist/components/docs/Header.svelte.d.ts +15 -2
package/dist/components/docs/MdxContent.svelte +1 -8
package/dist/components/docs/MdxContent.svelte.d.ts +10 -0
package/dist/components/docs/NotFoundContent.svelte +11 -2
package/dist/components/docs/NotFoundContent.svelte.d.ts +1 -0
package/dist/components/docs/ProductSwitcher.svelte +3 -2
package/dist/components/docs/SidebarMenuItems.svelte +7 -10
package/dist/components/docs/TabGroups.svelte +3 -2
package/dist/mdx-components.d.ts +22 -0
package/dist/mdx-security.js +12 -11
package/dist/mdx.js +42 -3
package/dist/rehype-base-path.d.ts +15 -0
package/dist/rehype-base-path.js +32 -0
package/dist/sidebar-utils.js +3 -10
package/dist/styles/globals.css +19 -8
package/dist/utils.d.ts +6 -8
package/dist/utils.js +8 -15
package/package.json +4 -2

package/config/rehype-base-path.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export function rehypeBasePath(options?: {}): (tree: any) => void;

package/config/svelte-config.js CHANGED Viewed

@@ -19,6 +19,7 @@ import rehypeKatex from 'rehype-katex'
 import rehypeRaw from 'rehype-raw'
 import fs from 'fs'
 import path from 'path'
+import { rehypeBasePath } from '../dist/rehype-base-path.js'
 /**
  * Get mdsvex preprocessor config with all Specra remark/rehype plugins
@@ -45,8 +46,59 @@ export function specraMdsvexConfig(options = {}) {
 }
 /**
- * Scan the docs/ directory and return prerender entries for all version root pages.
- * This ensures adapter-static discovers and prerenders every version, not just the active one.
+ * Read the deployment basePath from specra.config.json if present.
+ * Falls back to the BASE_PATH environment variable, then empty string.
+ */
+/**
+ * Normalize a base path: ensure leading slash, strip trailing slash.
+ * "task_flow" → "/task_flow", "/task_flow/" → "/task_flow", "" → ""
+ */
+function normalizeBasePath(bp) {
+  if (!bp) return ''
+  let normalized = bp.startsWith('/') ? bp : `/${bp}`
+  return normalized.replace(/\/+$/, '')
+}
+function resolveBasePath(configPath = path.join(process.cwd(), 'specra.config.json')) {
+  // Environment variable takes priority
+  if (process.env.BASE_PATH) return normalizeBasePath(process.env.BASE_PATH)
+  try {
+    if (fs.existsSync(configPath)) {
+      const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+      if (raw.deployment?.basePath) {
+        if (raw.deployment?.customDomain) return ''
+        return normalizeBasePath(raw.deployment.basePath)
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return ''
+}
+/**
+ * Scan the docs/ directory and return prerender entries for every
+ * version-root page across all products and the default (no-product)
+ * layout. SvelteKit's prerender crawler picks up child pages by
+ * following links, but the version-root pages themselves are leaves
+ * with no inbound link from a prerendered ancestor (the product
+ * dropdown switches between them client-side), so adapter-static
+ * needs them seeded explicitly. Without these entries, navigating
+ * from one product to another in a static build fetches a
+ * non-existent `__data.json` and falls back through to the SPA
+ * `index.html` — the client then JSON.parse's HTML and throws
+ * `Unexpected token '<', "<!doctype html>"`.
+ *
+ * Layouts we handle:
+ *   docs/v1/...                 → emit `/docs/v1`
+ *   docs/v2/...                 → emit `/docs/v2`
+ *   docs/sdk/_product_.json     → recurse: docs/sdk/v1 → emit `/docs/sdk/v1`
+ *   docs/api/_product_.json     → recurse: docs/api/v1 → emit `/docs/api/v1`
+ *
+ * `_product_.json` is the marker file Specra uses to identify a
+ * multi-product layout (the same marker the SDK's product loader
+ * reads).
  */
 function discoverVersionEntries(docsDir = path.join(process.cwd(), 'docs')) {
   const entries = ['/']
@@ -55,31 +107,68 @@ function discoverVersionEntries(docsDir = path.join(process.cwd(), 'docs')) {
     const items = fs.readdirSync(docsDir, { withFileTypes: true })
     for (const item of items) {
-      if (item.isDirectory() && /^v\d/.test(item.name)) {
+      if (!item.isDirectory()) continue
+      // Default-product version: docs/v1 → /docs/v1
+      if (/^v\d/.test(item.name)) {
         entries.push(`/docs/${item.name}`)
+        continue
+      }
+      // Multi-product: directory has a _product_.json marker. Recurse
+      // into it and emit one entry per version subdirectory.
+      const productDir = path.join(docsDir, item.name)
+      const productMarker = path.join(productDir, '_product_.json')
+      if (!fs.existsSync(productMarker)) continue
+      try {
+        const versionItems = fs.readdirSync(productDir, { withFileTypes: true })
+        for (const v of versionItems) {
+          if (v.isDirectory() && /^v\d/.test(v.name)) {
+            entries.push(`/docs/${item.name}/${v.name}`)
+          }
+        }
+      } catch {
+        // Ignore product-dir read errors — leave that product unseeded.
       }
     }
   } catch {
-    // Ignore errors — fall back to just '/'
+    // Ignore top-level errors — fall back to just '/'.
   }
   return entries
 }
 /**
- * Create a full SvelteKit config with Specra defaults
+ * Create a full SvelteKit config with Specra defaults.
+ * Automatically reads deployment.basePath from specra.config.json
+ * for GitHub Pages deployments.
  */
 export function specraConfig(options = {}) {
   const { vitePreprocess } = options.vitePreprocess || {}
   const userPrerender = options.kit?.prerender || {}
+  const basePath = options.kit?.paths?.base ?? resolveBasePath()
+  // Inject base path rehype plugin into mdsvex if basePath is set
+  const mdsvexOptions = options.mdsvex || {}
+  if (basePath) {
+    mdsvexOptions.rehypePlugins = [
+      ...(mdsvexOptions.rehypePlugins || []),
+      [rehypeBasePath, { basePath }],
+    ]
+  }
   return {
     extensions: ['.svelte', '.md', '.svx', '.mdx'],
     preprocess: [
       ...(vitePreprocess ? [vitePreprocess()] : []),
-      mdsvex(specraMdsvexConfig(options.mdsvex || {}))
+      mdsvex(specraMdsvexConfig(mdsvexOptions))
     ],
     kit: {
       ...options.kit,
+      paths: {
+        ...options.kit?.paths,
+        base: basePath,
+      },
       prerender: {
         handleHttpError: 'warn',
         handleMissingId: 'warn',

package/dist/components/docs/Breadcrumb.svelte CHANGED Viewed

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { ChevronRight } from 'lucide-svelte';
+  import { base } from '$app/paths';
   import { getConfigContext } from '../../stores/config.js';
   interface Props {
@@ -13,8 +14,8 @@
   let docsBase = $derived(
     product && product !== '_default_'
-      ? `/docs/${product}/${version}`
-      : `/docs/${version}`
+      ? `${base}/docs/${product}/${version}`
+      : `${base}/docs/${version}`
   );
   const configStore = getConfigContext();

package/dist/components/docs/CategoryIndex.svelte CHANGED Viewed

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { FileText, ArrowRight } from 'lucide-svelte';
+  import { base } from '$app/paths';
   import type { SpecraConfig } from '../../config.types.js';
   import type { Snippet } from 'svelte';
@@ -42,8 +43,8 @@
         // Match direct children of this category path
         if (!docPath.startsWith(categoryPath + '/')) return false;
         const remaining = docPath.slice(categoryPath.length + 1);
-        // Only direct children (no further slashes, or is an index)
-        return !remaining.includes('/') && remaining !== 'index';
+        // Only direct children (no further slashes)
+        return !remaining.includes('/');
       })
       .sort((a, b) => {
         const posA = a.meta?.sidebar_position ?? 999;
@@ -54,8 +55,8 @@
   const baseUrl = $derived(
     product && product !== '_default_'
-      ? `/docs/${product}`
-      : '/docs'
+      ? `${base}/docs/${product}`
+      : `${base}/docs`
   );
   // Note: We always use '/docs' as the base for non-product routes.

package/dist/components/docs/DocNavigation.svelte CHANGED Viewed

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { ChevronLeft, ChevronRight } from 'lucide-svelte';
+  import { base } from '$app/paths';
   interface NavDoc {
     title: string;
@@ -17,8 +18,8 @@
   let docsBase = $derived(
     product && product !== '_default_'
-      ? `/docs/${product}/${version}`
-      : `/docs/${version}`
+      ? `${base}/docs/${product}/${version}`
+      : `${base}/docs/${version}`
   );
 </script>

package/dist/components/docs/Footer.svelte CHANGED Viewed

@@ -1,7 +1,16 @@
 <script lang="ts">
   import type { SpecraConfig } from '../../config.types.js';
+  import { base } from '$app/paths';
   import Logo from './Logo.svelte';
+  /** Prefix internal links with base path */
+  function resolveHref(href: string): string {
+    if (href.startsWith('/') && !href.startsWith('//')) {
+      return `${base}${href}`;
+    }
+    return href;
+  }
   interface Props {
     config: SpecraConfig;
   }
@@ -25,7 +34,7 @@
               {#each column.items as item, itemIdx (itemIdx)}
                 <li>
                   <a
-                    href={item.href}
+                    href={resolveHref(item.href)}
                     class="text-sm text-muted-foreground hover:text-foreground transition-colors"
                   >
                     {item.label}

package/dist/components/docs/Header.svelte CHANGED Viewed

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { Search, Menu, Github, Twitter, MessageCircle } from 'lucide-svelte';
+  import { base } from '$app/paths';
   import { getConfigContext } from '../../stores/config.js';
   import { sidebarStore } from '../../stores/sidebar.js';
   import VersionSwitcher from './VersionSwitcher.svelte';
@@ -21,7 +22,8 @@
     hidden?: boolean;
   }
-  interface ProductItem {
+  /** Flat shape (from page components) */
+  interface ProductItemFlat {
     slug: string;
     label: string;
     icon?: string;
@@ -30,13 +32,27 @@
     isDefault: boolean;
   }
+  /** Nested shape (from SDK getProducts()) */
+  interface ProductItemNested {
+    slug: string;
+    config: {
+      label: string;
+      icon?: string;
+      badge?: string;
+      activeVersion?: string;
+    };
+    isDefault: boolean;
+  }
+  type ProductInput = ProductItemFlat | ProductItemNested;
   interface Props {
     currentVersion: string;
     versions: string[];
     versionsMeta?: VersionMeta[];
     versionBanner?: BannerConfig;
     config?: SpecraConfig;
-    products?: ProductItem[];
+    products?: ProductInput[];
     currentProduct?: string;
     subheader?: Snippet;
   }
@@ -95,7 +111,7 @@
       >
         <Menu class="h-5 w-5" />
       </button>
-      <a href="/" class="flex items-center gap-2">
+      <a href="{base}/" class="flex items-center gap-2">
         {#if !config.site.hideLogo}
           {#if config.site.logo}
             <Logo logo={config.site.logo} alt={config.site.title} className="w-18 object-contain" />

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

@@ -7,7 +7,8 @@ interface VersionMeta {
     badge?: string;
     hidden?: boolean;
 }
-interface ProductItem {
+/** Flat shape (from page components) */
+interface ProductItemFlat {
     slug: string;
     label: string;
     icon?: string;
@@ -15,13 +16,25 @@ interface ProductItem {
     activeVersion?: string;
     isDefault: boolean;
 }
+/** Nested shape (from SDK getProducts()) */
+interface ProductItemNested {
+    slug: string;
+    config: {
+        label: string;
+        icon?: string;
+        badge?: string;
+        activeVersion?: string;
+    };
+    isDefault: boolean;
+}
+type ProductInput = ProductItemFlat | ProductItemNested;
 interface Props {
     currentVersion: string;
     versions: string[];
     versionsMeta?: VersionMeta[];
     versionBanner?: BannerConfig;
     config?: SpecraConfig;
-    products?: ProductItem[];
+    products?: ProductInput[];
     currentProduct?: string;
     subheader?: Snippet;
 }

package/dist/components/docs/MdxContent.svelte CHANGED Viewed

@@ -1,14 +1,7 @@
 <script lang="ts">
   import MdxContent from './MdxContent.svelte';
   import type { Component } from 'svelte';
-  interface MdxNode {
-    type: 'html' | 'component';
-    content?: string;
-    name?: string;
-    props?: Record<string, any>;
-    children?: MdxNode[];
-  }
+  import type { MdxNode } from '../../mdx.js';
   interface Props {
     nodes: MdxNode[];

package/dist/components/docs/MdxContent.svelte.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import MdxContent from './MdxContent.svelte';
+import type { Component } from 'svelte';
+import type { MdxNode } from '../../mdx.js';
+interface Props {
+    nodes: MdxNode[];
+    components: Record<string, Component>;
+}
+declare const MdxContent: Component<Props, {}, "">;
+type MdxContent = ReturnType<typeof MdxContent>;
+export default MdxContent;

package/dist/components/docs/NotFoundContent.svelte CHANGED Viewed

@@ -1,13 +1,22 @@
 <script lang="ts">
   import { FileQuestion, Home, ArrowLeft } from 'lucide-svelte';
+  import { base } from '$app/paths';
   interface Props {
     version?: string;
+    product?: string;
   }
-  let { version = '' }: Props = $props();
+  let { version = '', product = '' }: Props = $props();
-  const homeLink = $derived(version ? `/${version}` : '/');
+  /** URL prefix: /docs/{product}/{version} for named products, /docs/{version} for default */
+  const homeLink = $derived(
+    product && product !== '_default_' && version
+      ? `${base}/docs/${product}/${version}`
+      : version
+        ? `${base}/docs/${version}`
+        : `${base}/`
+  );
 </script>
 <div class="flex flex-col items-center justify-center min-h-[60vh] text-center px-4">

package/dist/components/docs/NotFoundContent.svelte.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 interface Props {
     version?: string;
+    product?: string;
 }
 declare const NotFoundContent: import("svelte").Component<Props, {}, "">;
 type NotFoundContent = ReturnType<typeof NotFoundContent>;

package/dist/components/docs/ProductSwitcher.svelte CHANGED Viewed

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { ChevronDown, Check } from 'lucide-svelte';
   import { goto } from '$app/navigation';
+  import { base } from '$app/paths';
   import { browser } from '$app/environment';
   import Icon from './Icon.svelte';
@@ -107,9 +108,9 @@
     const version = product.activeVersion || 'v1.0.0';
     if (product.isDefault) {
-      goto(`/docs/${version}`);
+      goto(`${base}/docs/${version}`);
     } else {
-      goto(`/docs/${product.slug}/${version}`);
+      goto(`${base}/docs/${product.slug}/${version}`);
     }
   }

package/dist/components/docs/SidebarMenuItems.svelte CHANGED Viewed

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { page } from '$app/stores';
+  import { base } from '$app/paths';
   import { ChevronRight, ChevronDown, Lock } from 'lucide-svelte';
   import type { SpecraConfig } from '../../config.types.js';
   import Icon from './Icon.svelte';
@@ -50,11 +51,11 @@
   let { docs = [], version, product, onLinkClick, config, activeTabGroup }: Props = $props();
-  /** URL prefix: /docs/{product}/{version} for named products, /docs/{version} for default */
+  /** URL prefix: {base}/docs/{product}/{version} for named products, {base}/docs/{version} for default */
   let docsBase = $derived(
     product && product !== '_default_'
-      ? `/docs/${product}/${version}`
-      : `/docs/${version}`
+      ? `${base}/docs/${product}/${version}`
+      : `${base}/docs/${version}`
   );
   const STORAGE_KEY = 'specra-sidebar-collapsed';
@@ -134,9 +135,8 @@
         if (isIndexFile) {
           rootGroups[groupName].position = doc.sidebar_position ?? 999;
           rootGroups[groupName].icon = doc.categoryIcon;
-        } else {
-          rootGroups[groupName].items.push(doc);
         }
+        rootGroups[groupName].items.push(doc);
         return;
       }
@@ -179,17 +179,14 @@
               if (doc.categoryIcon) {
                 currentLevel[folder].icon = doc.categoryIcon;
               }
-            } else {
-              currentLevel[folder].items.push(doc);
             }
+            currentLevel[folder].items.push(doc);
           }
           currentLevel = currentLevel[folder].children;
         }
       } else {
-        if (!isIndexFile) {
-          standalone.push(doc);
-        }
+        standalone.push(doc);
       }
     });

package/dist/components/docs/TabGroups.svelte CHANGED Viewed

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { ChevronDown } from 'lucide-svelte';
   import { goto } from '$app/navigation';
+  import { base } from '$app/paths';
   import type { TabGroup, SpecraConfig } from '../../config.types.js';
   import Icon from './Icon.svelte';
@@ -32,8 +33,8 @@
   let docsBase = $derived(
     product && product !== '_default_' && version
-      ? `/docs/${product}/${version}`
-      : version ? `/docs/${version}` : '/docs'
+      ? `${base}/docs/${product}/${version}`
+      : version ? `${base}/docs/${version}` : `${base}/docs`
   );
   let dropdownOpen = $state(false);

package/dist/mdx-components.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * MDX/mdsvex component map for Specra documentation.
+ *
+ * In mdsvex, custom components are imported directly in .svx files.
+ * This file exports the component map for programmatic use.
+ *
+ * Usage in .svx files:
+ * ```svelte
+ * <script>
+ *   import { Callout, CodeBlock, Tabs, Tab } from 'specra/components'
+ * </script>
+ *
+ * <Callout type="info">This is a callout</Callout>
+ * ```
+ */
+import type { Component } from 'svelte';
+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';
+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.
+ */
+export declare const mdxComponents: Record<string, Component>;

package/dist/mdx-security.js CHANGED Viewed

@@ -44,22 +44,23 @@ export function validatePathWithinDirectory(filePath, allowedDir) {
  * These patterns can execute arbitrary code during SSR
  */
 const DANGEROUS_PATTERNS = [
-    // JavaScript execution
-    /eval\s*\(/gi,
-    /Function\s*\(/gi,
-    /import\s*\(/gi,
-    /require\s*\(/gi,
+    // JavaScript execution — require expression context (after { ; = or line start)
+    // to avoid false positives on prose like "bulk import (CSV...)" or "fetch (data)"
+    /(?:^|[{;=,])\s*eval\s*\(/gim,
+    /(?:^|[{;=,])\s*Function\s*\(/gim,
+    /(?:^|[{;=,])\s*import\s*\(/gim,
+    /(?:^|[{;=,])\s*require\s*\(/gim,
     // File system access
     /fs\.[a-z]+/gi,
-    /readFile/gi,
-    /writeFile/gi,
+    /(?:^|[{;=,])\s*readFile/gim,
+    /(?:^|[{;=,])\s*writeFile/gim,
     /process\.env/gi,
-    // Network requests during SSR (legitimate client-side usage should use components)
-    /fetch\s*\(/gi,
+    // Network requests during SSR — require expression context
+    /(?:^|[{;=,])\s*fetch\s*\(/gim,
     // Dangerous Node.js modules
     /child_process/gi,
-    /exec\s*\(/gi,
-    /spawn\s*\(/gi,
+    /(?:^|[{;=,])\s*exec\s*\(/gim,
+    /(?:^|[{;=,])\s*spawn\s*\(/gim,
     // Script tag injection
     /<script[>\s]/gi,
     /javascript:/gi,

package/dist/mdx.js CHANGED Viewed

@@ -1,6 +1,8 @@
 import fs from "fs";
 import path from "path";
 import matter from "gray-matter";
+import yaml from "js-yaml";
+import { rehypeBasePath } from "./rehype-base-path.js";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
@@ -394,15 +396,41 @@ function parseJsxExpression(expr) {
 /**
  * Process markdown content to HTML using remark/rehype pipeline.
  */
+function normalizeBasePath(bp) {
+    if (!bp)
+        return '';
+    let normalized = bp.startsWith('/') ? bp : `/${bp}`;
+    return normalized.replace(/\/+$/, '');
+}
+function resolveDeploymentBasePath() {
+    if (process.env.BASE_PATH)
+        return normalizeBasePath(process.env.BASE_PATH);
+    try {
+        const configPath = path.join(process.cwd(), 'specra.config.json');
+        if (fs.existsSync(configPath)) {
+            const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            if (raw.deployment?.basePath && !raw.deployment?.customDomain) {
+                return normalizeBasePath(raw.deployment.basePath);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return '';
+}
 async function processMarkdownToHtml(markdown) {
-    const result = await unified()
+    const basePath = resolveDeploymentBasePath();
+    const processor = unified()
         .use(remarkParse)
         .use(remarkGfm)
         .use(remarkMath)
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(rehypeSlug)
-        .use(rehypeKatex)
+        .use(rehypeKatex);
+    if (basePath) {
+        processor.use(rehypeBasePath, { basePath });
+    }
+    const result = await processor
         .use(rehypeStringify)
         .process(markdown);
     return String(result);
@@ -1045,6 +1073,7 @@ async function processMarkdownToMdxNodes(markdown) {
     const dedented = dedentComponentChildren(preprocessed);
     // Ensure component block integrity in the markdown
     const normalized = ensureComponentBlockIntegrity(dedented);
+    const basePath = resolveDeploymentBasePath();
     const processor = unified()
         .use(remarkParse)
         .use(remarkGfm)
@@ -1053,6 +1082,9 @@ async function processMarkdownToMdxNodes(markdown) {
         .use(rehypeRaw)
         .use(rehypeSlug)
         .use(rehypeKatex);
+    if (basePath) {
+        processor.use(rehypeBasePath, { basePath });
+    }
     const mdast = processor.parse(normalized);
     const hast = await processor.run(mdast);
     // The hast root has children - process them into MdxNodes
@@ -1135,7 +1167,14 @@ function readDocFromFile(filePath, originalSlug) {
             return null;
         }
         const fileContents = fs.readFileSync(filePath, "utf8");
-        const { data, content } = matter(fileContents);
+        const { data, content } = matter(fileContents, {
+            engines: {
+                yaml: {
+                    parse: (str) => yaml.load(str),
+                    stringify: (obj) => yaml.dump(obj),
+                },
+            },
+        });
         // Security: Validate MDX content for dangerous patterns
         const securityCheck = validateMDXSecurity(content, {
             strictMode: process.env.NODE_ENV === 'production',

package/dist/rehype-base-path.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * Rehype plugin that prefixes internal absolute links with a base path.
+ * Internal links start with "/" and don't start with "http" or "//".
+ *
+ * Used for GitHub Pages deployments where the site lives under a subpath.
+ *
+ * Manually walks the tree to avoid ESM/CJS issues with unist-util-visit
+ * when loaded from svelte-config.js at Node.js config time.
+ */
+import type { Root } from 'hast';
+interface Options {
+    basePath?: string;
+}
+export declare function rehypeBasePath(options?: Options): (tree: Root) => void;
+export {};

package/dist/rehype-base-path.js ADDED Viewed

@@ -0,0 +1,32 @@
+function walkElements(nodes, fn) {
+    for (const node of nodes) {
+        if (node.type === 'element') {
+            fn(node);
+            if (node.children) {
+                walkElements(node.children, fn);
+            }
+        }
+    }
+}
+export function rehypeBasePath(options = {}) {
+    const { basePath = '' } = options;
+    if (!basePath)
+        return () => { };
+    const cleanBase = basePath.replace(/\/$/, '');
+    return (tree) => {
+        walkElements(tree.children, (node) => {
+            if (node.tagName === 'a' && node.properties?.href) {
+                const href = node.properties.href;
+                if (typeof href === 'string' && href.startsWith('/') && !href.startsWith('//') && !href.startsWith(cleanBase + '/')) {
+                    node.properties.href = cleanBase + href;
+                }
+            }
+            if (node.tagName === 'img' && node.properties?.src) {
+                const src = node.properties.src;
+                if (typeof src === 'string' && src.startsWith('/') && !src.startsWith('//') && !src.startsWith(cleanBase + '/')) {
+                    node.properties.src = cleanBase + src;
+                }
+            }
+        });
+    };
+}

package/dist/sidebar-utils.js CHANGED Viewed

@@ -79,13 +79,10 @@ export function buildSidebarStructure(docs) {
                 };
             }
             if (isIndexFile) {
-                // Use categoryPosition if available (from _category_.json), otherwise sidebar_position from frontmatter
                 rootGroups[groupName].position = doc.categoryPosition ?? doc.meta.sidebar_position ?? 999;
                 rootGroups[groupName].icon = doc.categoryIcon;
             }
-            else {
-                rootGroups[groupName].items.push(doc);
-            }
+            rootGroups[groupName].items.push(doc);
             return;
         }
         if (pathParts.length > 1) {
@@ -127,17 +124,13 @@ export function buildSidebarStructure(docs) {
                             currentLevel[folder].defaultCollapsed = doc.categoryCollapsed;
                         }
                     }
-                    else {
-                        currentLevel[folder].items.push(doc);
-                    }
+                    currentLevel[folder].items.push(doc);
                 }
                 currentLevel = currentLevel[folder].children;
             }
         }
         else {
-            if (!isIndexFile) {
-                standalone.push(doc);
-            }
+            standalone.push(doc);
         }
     });
     return { rootGroups, standalone };

package/dist/styles/globals.css CHANGED Viewed

@@ -159,28 +159,39 @@
     text-decoration: none;
   }
-  /* Link styling - primary color, no underline until hover */
+  /* Prose text links - underlined for readability */
   main .prose a {
     color: var(--color-primary);
-    text-decoration: none;
-    transition: color 0.2s ease, text-decoration 0.2s ease;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    text-decoration-thickness: 1px;
+    text-decoration-color: color-mix(in srgb, var(--color-primary) 40%, transparent);
+    transition: text-decoration-color 0.2s ease;
   }
   main .prose a:hover {
-    text-decoration: none !important;
-    color: var(--color-primary);
+    text-decoration-color: var(--color-primary);
   }
-  /* Prose links in documentation */
   .prose a {
     color: var(--color-primary);
-    text-decoration: none !important;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    text-decoration-thickness: 1px;
+    text-decoration-color: color-mix(in srgb, var(--color-primary) 40%, transparent);
     font-weight: 500;
   }
   .prose a:hover {
+    text-decoration-color: var(--color-primary);
+  }
+  /* Navigation/UI links inside prose - no underline */
+  .prose .not-prose a,
+  .prose nav a,
+  .prose [data-doc-nav] a,
+  .prose .doc-navigation a {
     text-decoration: none !important;
-    color: var(--color-primary);
   }
   /* Sidebar links - no underline on hover */

package/dist/utils.d.ts CHANGED Viewed

@@ -1,13 +1,11 @@
 import { type ClassValue } from 'clsx';
 export declare function cn(...inputs: ClassValue[]): string;
 /**
- * Get the correct asset path based on deployment configuration
- * Handles different deployment scenarios:
- * - Vercel/Node.js hosting (standalone build): No basePath needed
- * - GitHub Pages without custom domain: Uses basePath from config
- * - Static hosting with custom domain: No basePath needed
+ * Get the correct asset path based on deployment configuration.
+ * Uses SvelteKit's base path (from kit.paths.base) which is resolved
+ * from deployment.basePath in specra.config.json or the BASE_PATH env var.
  *
- * @param path - The asset path (can start with or without '/')
- * @returns The properly formatted asset path
+ * @param assetPath - The asset path (can start with or without '/')
+ * @returns The properly formatted asset path with base prefix
  */
-export declare function getAssetPath(path: string): string;
+export declare function getAssetPath(assetPath: string): string;

package/dist/utils.js CHANGED Viewed

@@ -4,27 +4,20 @@ export function cn(...inputs) {
     return twMerge(clsx(inputs));
 }
 /**
- * Get the correct asset path based on deployment configuration
- * Handles different deployment scenarios:
- * - Vercel/Node.js hosting (standalone build): No basePath needed
- * - GitHub Pages without custom domain: Uses basePath from config
- * - Static hosting with custom domain: No basePath needed
+ * Get the correct asset path based on deployment configuration.
+ * Uses SvelteKit's base path (from kit.paths.base) which is resolved
+ * from deployment.basePath in specra.config.json or the BASE_PATH env var.
  *
- * @param path - The asset path (can start with or without '/')
- * @returns The properly formatted asset path
+ * @param assetPath - The asset path (can start with or without '/')
+ * @returns The properly formatted asset path with base prefix
  */
-export function getAssetPath(path) {
-    // Get basePath from Next.js config (set during build for static exports)
-    const basePath = process.env.NEXT_PUBLIC_BASE_PATH || process.env.__NEXT_ROUTER_BASEPATH || '';
-    // Normalize the input path: ensure it starts with '/'
-    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-    // If we have a basePath (GitHub Pages without custom domain), prepend it
+export function getAssetPath(assetPath) {
+    const basePath = process.env.BASE_PATH || '';
+    const normalizedPath = assetPath.startsWith('/') ? assetPath : `/${assetPath}`;
     if (basePath) {
-        // Normalize basePath: remove trailing slash, ensure leading slash
         const normalizedBase = basePath.startsWith('/') ? basePath : `/${basePath}`;
         const cleanBase = normalizedBase.replace(/\/$/, '');
         return `${cleanBase}${normalizedPath}`;
     }
-    // Default: return the normalized path (works for Vercel, custom domains, and dev)
     return normalizedPath;
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.51",
+  "version": "0.2.55",
   "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",
@@ -78,13 +78,14 @@
     "date-fns": "^4.1.0",
     "embla-carousel-svelte": "^8.5.1",
     "gray-matter": "^4.0.3",
+    "hast-util-to-html": "^9.0.0",
+    "js-yaml": "^4.1.1",
     "katex": "^0.16.27",
     "lucide-svelte": "^0.454.0",
     "mdsvex": "^0.12.0",
     "meilisearch": "^0.54.0",
     "mermaid": "^11.12.2",
     "mode-watcher": "^0.5.0",
-    "hast-util-to-html": "^9.0.0",
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
@@ -103,6 +104,7 @@
     "@sveltejs/kit": "^2.0.0",
     "@sveltejs/package": "^2.0.0",
     "@sveltejs/vite-plugin-svelte": "^6.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22",
     "svelte": "^5.0.0",
     "svelte-check": "^4.0.0",