specra 0.2.13 → 0.2.15

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
@@ -48,18 +49,26 @@ 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.
  */
+/**
+ * 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 process.env.BASE_PATH
+  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) {
-        const bp = raw.deployment.basePath
-        // If custom domain is set, ignore basePath
         if (raw.deployment?.customDomain) return ''
-        return bp.startsWith('/') ? bp : `/${bp}`
+        return normalizeBasePath(raw.deployment.basePath)
       }
     }
   } catch {
@@ -72,7 +81,7 @@ function resolveBasePath(configPath = path.join(process.cwd(), 'specra.config.js
  * 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(basePath = '', docsDir = path.join(process.cwd(), 'docs')) {
+function discoverVersionEntries(docsDir = path.join(process.cwd(), 'docs')) {
   const entries = ['/']
   try {
     if (!fs.existsSync(docsDir)) return entries
@@ -80,7 +89,7 @@ function discoverVersionEntries(basePath = '', docsDir = path.join(process.cwd()
     const items = fs.readdirSync(docsDir, { withFileTypes: true })
     for (const item of items) {
       if (item.isDirectory() && /^v\d/.test(item.name)) {
-        entries.push(`${basePath}/docs/${item.name}`)
+        entries.push(`/docs/${item.name}`)
       }
     }
   } catch {
@@ -99,11 +108,20 @@ export function specraConfig(options = {}) {
   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,
@@ -115,7 +133,7 @@ export function specraConfig(options = {}) {
         handleHttpError: 'warn',
         handleMissingId: 'warn',
         handleUnseenRoutes: 'warn',
-        entries: discoverVersionEntries(basePath),
+        entries: discoverVersionEntries(),
         ...userPrerender,
       }
     }

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,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);
@@ -1046,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)
@@ -1054,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

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/package.json

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