specra 0.2.12 → 0.2.14

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

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

package/config/svelte-config.js

@@ -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
@@ -44,6 +45,30 @@ 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.
@@ -66,20 +91,36 @@ 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()
+
+  // 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

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

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

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

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

@@ -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';
@@ -110,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/NotFoundContent.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { FileQuestion, Home, ArrowLeft } from 'lucide-svelte';
+  import { base } from '$app/paths';
 
   interface Props {
     version?: string;
@@ -11,10 +12,10 @@
   /** URL prefix: /docs/{product}/{version} for named products, /docs/{version} for default */
   const homeLink = $derived(
     product && product !== '_default_' && version
-      ? `/docs/${product}/${version}`
+      ? `${base}/docs/${product}/${version}`
       : version
-        ? `/docs/${version}`
-        : '/'
+        ? `${base}/docs/${version}`
+        : `${base}/`
   );
 </script>
 

package/dist/components/docs/ProductSwitcher.svelte

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

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

package/dist/components/docs/TabGroups.svelte

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

@@ -2,6 +2,7 @@ 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";
@@ -395,15 +396,36 @@ function parseJsxExpression(expr) {
 /**
  * Process markdown content to HTML using remark/rehype pipeline.
  */
+function resolveDeploymentBasePath() {
+    if (process.env.BASE_PATH)
+        return 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) {
+                const bp = raw.deployment.basePath;
+                return bp.startsWith('/') ? bp : `/${bp}`;
+            }
+        }
+    }
+    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);
@@ -1046,6 +1068,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)
@@ -1054,6 +1077,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

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+import { visit } from 'unist-util-visit';
+export function rehypeBasePath(options = {}) {
+    const { basePath = '' } = options;
+    if (!basePath)
+        return () => { };
+    const cleanBase = basePath.replace(/\/$/, '');
+    return (tree) => {
+        visit(tree, 'element', (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/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.12",
+  "version": "0.2.14",
   "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",