specra 0.2.11 → 0.2.13

package/config/svelte-config.js

@@ -44,11 +44,35 @@ export function specraMdsvexConfig(options = {}) {
   }
 }
 
+/**
+ * Read the deployment basePath from specra.config.json if present.
+ * Falls back to the BASE_PATH environment variable, then empty string.
+ */
+function resolveBasePath(configPath = path.join(process.cwd(), 'specra.config.json')) {
+  // Environment variable takes priority
+  if (process.env.BASE_PATH) return process.env.BASE_PATH
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+      if (raw.deployment?.basePath) {
+        const bp = raw.deployment.basePath
+        // If custom domain is set, ignore basePath
+        if (raw.deployment?.customDomain) return ''
+        return bp.startsWith('/') ? bp : `/${bp}`
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return ''
+}
+
 /**
  * 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.
  */
-function discoverVersionEntries(docsDir = path.join(process.cwd(), 'docs')) {
+function discoverVersionEntries(basePath = '', docsDir = path.join(process.cwd(), 'docs')) {
   const entries = ['/']
   try {
     if (!fs.existsSync(docsDir)) return entries
@@ -56,7 +80,7 @@ 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)) {
-        entries.push(`/docs/${item.name}`)
+        entries.push(`${basePath}/docs/${item.name}`)
       }
     }
   } catch {
@@ -66,11 +90,14 @@ function discoverVersionEntries(docsDir = path.join(process.cwd(), 'docs')) {
 }
 
 /**
- * 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()
 
   return {
     extensions: ['.svelte', '.md', '.svx', '.mdx'],
@@ -80,11 +107,15 @@ export function specraConfig(options = {}) {
     ],
     kit: {
       ...options.kit,
+      paths: {
+        ...options.kit?.paths,
+        base: basePath,
+      },
       prerender: {
         handleHttpError: 'warn',
         handleMissingId: 'warn',
         handleUnseenRoutes: 'warn',
-        entries: discoverVersionEntries(),
+        entries: discoverVersionEntries(basePath),
         ...userPrerender,
       }
     }

package/dist/components/docs/Header.svelte

@@ -21,7 +21,8 @@
     hidden?: boolean;
   }
 
-  interface ProductItem {
+  /** Flat shape (from page components) */
+  interface ProductItemFlat {
     slug: string;
     label: string;
     icon?: string;
@@ -30,13 +31,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;
   }

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

@@ -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/mdx.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import matter from "gray-matter";
+import yaml from "js-yaml";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
@@ -1135,7 +1136,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/utils.d.ts

@@ -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

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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",