specra-cli 0.3.0

package/templates/minimal/src/routes/+page.svelte

@@ -0,0 +1,149 @@
+<script lang="ts">
+  import { ArrowRight, BookOpen, Zap, Code, Github, Twitter, Linkedin } from 'lucide-svelte';
+  import { Button, SiteBanner, Logo } from 'specra/components';
+
+  let { data } = $props();
+  const config = data.config;
+  const activeVersion = config.site.activeVersion || 'v1.0.0';
+  const docsUrl = `/docs/${activeVersion}/about`;
+</script>
+
+<svelte:head>
+  <title>{config.site.title}</title>
+  <meta name="description" content={config.site.description || 'Modern documentation platform'} />
+</svelte:head>
+
+<div class="min-h-screen bg-background">
+  <SiteBanner {config} />
+  <header class="border-b border-border">
+    <div class="container flex h-16 items-center justify-between px-6 mx-auto">
+      <a href="/" class="flex items-center gap-2">
+        <Logo logo={config.site.logo} alt={config.site.title} class="w-18 object-contain" />
+        <span class="font-semibold text-lg text-foreground">Specra</span>
+      </a>
+      <div class="flex items-center gap-6">
+        <a href={docsUrl} class="text-sm text-muted-foreground hover:text-foreground transition-colors">
+          Documentation
+        </a>
+        {#if config?.social?.github}
+          <a href={config.social.github} target="_blank" rel="noopener noreferrer" class="text-muted-foreground hover:text-foreground transition-colors">
+            <Github class="h-5 w-5" />
+          </a>
+        {/if}
+        <Button href={docsUrl}>Get Started</Button>
+      </div>
+    </div>
+  </header>
+
+  <main class="container px-6 mx-auto">
+    <!-- Hero Section -->
+    <div class="mx-auto text-center space-y-6 py-20 max-w-4xl">
+      <h1 class="text-5xl md:text-6xl font-bold tracking-tight text-foreground">
+        Beautiful documentation made <span class="text-primary">simple</span>
+      </h1>
+      <p class="text-xl md:text-2xl text-muted-foreground leading-relaxed max-w-3xl mx-auto">
+        The modern documentation framework that grows with your project
+      </p>
+      <p class="text-base md:text-lg text-muted-foreground leading-relaxed max-w-2xl mx-auto">
+        Built for developers who want powerful, flexible documentation without the complexity.
+        Write in MDX, configure with ease, and ship beautiful docs in minutes.
+      </p>
+      <div class="flex items-center justify-center gap-4 pt-4">
+        <Button href={docsUrl} size="lg">
+          Get Started
+          <ArrowRight class="ml-2 h-4 w-4" />
+        </Button>
+        {#if config?.social?.github}
+          <Button href={config.social.github} size="lg" variant="outline">
+            <Github class="mr-2 h-4 w-4" />
+            View on GitHub
+          </Button>
+        {/if}
+      </div>
+    </div>
+
+    <!-- Key Features -->
+    <div class="grid md:grid-cols-3 gap-6 py-16 max-w-6xl mx-auto">
+      <div class="p-6 rounded-lg border border-border bg-card hover:shadow-md transition-shadow">
+        <div class="h-12 w-12 rounded-lg bg-primary/10 flex items-center justify-center mb-4">
+          <BookOpen class="h-6 w-6 text-primary" />
+        </div>
+        <h3 class="text-lg font-semibold text-foreground mb-2">MDX-Powered</h3>
+        <p class="text-sm text-muted-foreground leading-relaxed">
+          Write your docs in MDX with support for custom components, code blocks with syntax highlighting, and rich interactive content.
+        </p>
+      </div>
+
+      <div class="p-6 rounded-lg border border-border bg-card hover:shadow-md transition-shadow">
+        <div class="h-12 w-12 rounded-lg bg-primary/10 flex items-center justify-center mb-4">
+          <Zap class="h-6 w-6 text-primary" />
+        </div>
+        <h3 class="text-lg font-semibold text-foreground mb-2">Lightning Fast</h3>
+        <p class="text-sm text-muted-foreground leading-relaxed">
+          Built on SvelteKit for optimal performance. Server-side rendering, instant page loads, and seamless navigation out of the box.
+        </p>
+      </div>
+
+      <div class="p-6 rounded-lg border border-border bg-card hover:shadow-md transition-shadow">
+        <div class="h-12 w-12 rounded-lg bg-primary/10 flex items-center justify-center mb-4">
+          <Code class="h-6 w-6 text-primary" />
+        </div>
+        <h3 class="text-lg font-semibold text-foreground mb-2">Developer First</h3>
+        <p class="text-sm text-muted-foreground leading-relaxed">
+          Version control friendly, Git-based workflow, and full TypeScript support. Your docs live alongside your code.
+        </p>
+      </div>
+    </div>
+
+    <!-- CTA Section -->
+    <div class="py-16 max-w-4xl mx-auto">
+      <div class="rounded-xl border border-border bg-card p-8 md:p-12 text-center space-y-6">
+        <h2 class="text-3xl md:text-4xl font-bold text-foreground">Ready to Get Started?</h2>
+        <p class="text-muted-foreground max-w-2xl mx-auto">
+          Create beautiful, versioned documentation for your project in minutes.<br />
+          Specra gives you everything you need to write, organize, and publish great docs.
+        </p>
+        <div class="flex flex-col sm:flex-row items-center justify-center gap-4 pt-2">
+          <Button href={docsUrl} size="lg" variant="default">
+            Read the Docs
+            <ArrowRight class="ml-2 h-4 w-4" />
+          </Button>
+          {#if config?.social?.github}
+            <Button href={config.social.github} size="lg" variant="outline">
+              <Github class="mr-2 h-4 w-4" />
+              Star on GitHub
+            </Button>
+          {/if}
+        </div>
+      </div>
+    </div>
+
+    <!-- Community Section -->
+    <div class="py-16 max-w-3xl mx-auto text-center space-y-6">
+      <h2 class="text-2xl md:text-3xl font-bold text-foreground">Join the Community</h2>
+      <p class="text-muted-foreground">
+        Specra is open source and community-driven. Connect with developers and stay updated.
+      </p>
+      <div class="flex items-center justify-center gap-4 pt-4">
+        {#if config?.social?.github}
+          <Button href={config.social.github} variant="outline" size="lg">
+            <Github class="mr-2 h-5 w-5" />
+            GitHub
+          </Button>
+        {/if}
+        {#if config?.social?.twitter}
+          <Button href={config.social.twitter} variant="outline" size="lg">
+            <Twitter class="mr-2 h-5 w-5" />
+            Twitter
+          </Button>
+        {/if}
+        {#if config?.social?.linkedin}
+          <Button href={config.social.linkedin} variant="outline" size="lg">
+            <Linkedin class="mr-2 h-5 w-5" />
+            LinkedIn
+          </Button>
+        {/if}
+      </div>
+    </div>
+  </main>
+</div>

package/templates/minimal/src/routes/docs/[product=product]/[version]/+layout.server.ts

@@ -0,0 +1,40 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, getProducts, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { product, version } = params;
+
+  // Verify this is a valid product — if not, fall through to 404
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {};
+  }
+
+  const i18nConfig = getI18nConfig();
+  const defaultLocale = i18nConfig?.defaultLocale || 'en';
+
+  // Block access to hidden versions — redirect to product's active version
+  const currentVersionConfig = loadVersionConfig(version, product);
+  if (currentVersionConfig?.hidden) {
+    const config = getEffectiveConfig(version, product);
+    const activeVersion = matchedProduct.config.activeVersion || config.site?.activeVersion || 'v1.0.0';
+    throw redirect(302, `/docs/${product}/${activeVersion}`);
+  }
+
+  const allDocs = await getCachedAllDocs(version, defaultLocale, product);
+  const versions = getCachedVersions(product);
+  const config = getEffectiveConfig(version, product);
+  const versionsMeta = getVersionsMeta(versions, product);
+
+  return {
+    allDocs,
+    versions,
+    versionsMeta,
+    config,
+    product,
+    products,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

package/templates/minimal/src/routes/docs/[product=product]/[version]/+page.server.ts

@@ -0,0 +1,24 @@
+import { redirect } from '@sveltejs/kit';
+import { getCachedAllDocs, getProducts } from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { product, version } = params;
+
+  // Verify product exists
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {};
+  }
+
+  const docs = await getCachedAllDocs(version, undefined, product);
+
+  if (docs.length === 0) {
+    const activeVersion = matchedProduct.config.activeVersion || 'v1.0.0';
+    redirect(302, `/docs/${product}/${activeVersion}`);
+  }
+
+  // Redirect to first doc in this product's version
+  redirect(302, `/docs/${product}/${version}/${docs[0].slug}`);
+};

package/templates/minimal/src/routes/docs/[product=product]/[version]/[...slug]/+page.server.ts

@@ -0,0 +1,131 @@
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getI18nConfig,
+  getProducts,
+} from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { product, version, slug: slugArray } = params;
+  const slug = slugArray.replace(/\/$/, '');
+
+  // Verify product exists
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {
+      version,
+      slug,
+      product,
+      isCategory: false,
+      isNotFound: true,
+      doc: null,
+      categoryTitle: null,
+      categoryDescription: null,
+      categoryTabGroup: undefined,
+      toc: [],
+      previous: null,
+      next: null,
+      title: 'Page Not Found',
+      description: 'The requested documentation page could not be found.',
+      ogUrl: `/docs/${product}/${version}/${slug}`,
+    };
+  }
+
+  const i18nConfig = getI18nConfig();
+  const slugParts = slug.split('/');
+  let locale: string | undefined;
+  if (i18nConfig && i18nConfig.locales.includes(slugParts[0])) {
+    locale = slugParts[0];
+  }
+
+  const allDocs = await getCachedAllDocs(version, locale, product);
+  const isCategory = isCategoryPage(slug, allDocs);
+  const doc = await getCachedDocBySlug(slug, version, product);
+  const urlPrefix = `/docs/${product}/${version}`;
+
+  let title = 'Page Not Found';
+  let description = 'The requested documentation page could not be found.';
+  let ogUrl = `${urlPrefix}/${slug}`;
+
+  if (doc) {
+    title = doc.meta.title || doc.title;
+    description = doc.meta.description || `Documentation for ${title}`;
+  }
+
+  if (!doc && isCategory) {
+    const categoryDoc = allDocs.find((d) => d.slug.startsWith(slug + '/'));
+    const categoryTabGroup = categoryDoc?.meta?.tab_group || categoryDoc?.categoryTabGroup;
+    const categoryTitle = slug
+      .split('/')
+      .pop()
+      ?.replace(/-/g, ' ')
+      .replace(/\b\w/g, (l) => l.toUpperCase()) || 'Category';
+
+    return {
+      version,
+      slug,
+      product,
+      isCategory: true,
+      isNotFound: false,
+      doc: null,
+      categoryTitle,
+      categoryDescription: 'Browse the documentation in this section.',
+      categoryTabGroup,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+
+  if (!doc) {
+    return {
+      version,
+      slug,
+      product,
+      isCategory: false,
+      isNotFound: true,
+      doc: null,
+      categoryTitle: null,
+      categoryDescription: null,
+      categoryTabGroup: undefined,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+
+  const toc = extractTableOfContents(doc.meta.content || doc.content);
+  const { previous, next } = getAdjacentDocs(slug, allDocs);
+  const showCategoryIndex = isCategory && !!doc;
+  const matchingDoc = allDocs.find((d) => d.slug === slug);
+  const currentPageTabGroup = doc.meta?.tab_group || matchingDoc?.categoryTabGroup;
+
+  return {
+    version,
+    slug,
+    product,
+    isCategory: showCategoryIndex,
+    isNotFound: false,
+    doc,
+    categoryTitle: null,
+    categoryDescription: null,
+    categoryTabGroup: currentPageTabGroup,
+    toc,
+    previous: previous ? { title: previous.meta.title, slug: previous.slug } : null,
+    next: next ? { title: next.meta.title, slug: next.slug } : null,
+    title,
+    description,
+    ogUrl,
+  };
+};

package/templates/minimal/src/routes/docs/[product=product]/[version]/[...slug]/+page.svelte

@@ -0,0 +1,180 @@
+<script lang="ts">
+  import {
+    TableOfContents,
+    Header,
+    TabGroups,
+    DocLayout,
+    CategoryIndex,
+    HotReloadIndicator,
+    DevModeBadge,
+    MdxHotReload,
+    MdxContent,
+    NotFoundContent,
+    SearchHighlight,
+    MobileDocLayout,
+    mdxComponents,
+  } from 'specra/components';
+  import type { PageData } from './$types';
+
+  let { data }: { data: PageData } = $props();
+
+  let allDocsCompat: any[] = $derived(data.allDocs);
+  let previousDoc = $derived(data.previous ?? undefined);
+  let nextDoc = $derived(data.next ?? undefined);
+  let categoryTitle = $derived(data.categoryTitle ?? undefined);
+  let categoryDescription = $derived(data.categoryDescription ?? undefined);
+</script>
+
+<svelte:head>
+  <title>{data.title}</title>
+  <meta name="description" content={data.description} />
+  <meta property="og:title" content={data.title} />
+  <meta property="og:description" content={data.description} />
+  <meta property="og:url" content={data.ogUrl} />
+  <meta property="og:site_name" content="Documentation Platform" />
+  <meta property="og:type" content="article" />
+  <meta property="og:locale" content="en_US" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content={data.title} />
+  <meta name="twitter:description" content={data.description} />
+  <link rel="canonical" href={data.ogUrl} />
+</svelte:head>
+
+{#if !data.doc && data.isCategory}
+  <!-- Category page without doc content -->
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    product={data.product}
+    config={data.config}
+    activeTabGroup={data.categoryTabGroup}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products} currentProduct={data.product}>
+        {#snippet subheader()}
+          {#if data.config.navigation?.tabGroups && data.config.navigation.tabGroups.length > 0}
+            <TabGroups
+              tabGroups={data.config.navigation.tabGroups}
+              activeTabId={data.categoryTabGroup}
+              docs={allDocsCompat}
+              version={data.version}
+              product={data.product}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    <CategoryIndex
+      categoryPath={data.slug}
+      version={data.version}
+      product={data.product}
+      allDocs={allDocsCompat}
+      title={categoryTitle}
+      description={categoryDescription}
+      config={data.config}
+    />
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{:else if data.isNotFound}
+  <!-- Not found -->
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    product={data.product}
+    config={data.config}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products} currentProduct={data.product}>
+        {#snippet subheader()}
+          {#if data.config.navigation?.tabGroups && data.config.navigation.tabGroups.length > 0}
+            <TabGroups
+              tabGroups={data.config.navigation.tabGroups}
+              activeTabId={data.categoryTabGroup}
+              docs={allDocsCompat}
+              version={data.version}
+              product={data.product}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    <NotFoundContent version={data.version} />
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{:else if data.doc}
+  <!-- Normal doc or category with doc content -->
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    product={data.product}
+    config={data.config}
+    activeTabGroup={data.categoryTabGroup}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products} currentProduct={data.product}>
+        {#snippet subheader()}
+          {#if data.config.navigation?.tabGroups && data.config.navigation.tabGroups.length > 0}
+            <TabGroups
+              tabGroups={data.config.navigation.tabGroups}
+              activeTabId={data.categoryTabGroup}
+              docs={allDocsCompat}
+              version={data.version}
+              product={data.product}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    {#snippet toc()}
+      {#if !data.isCategory}
+        <TableOfContents items={data.toc} config={data.config} />
+      {/if}
+    {/snippet}
+
+    {#if data.isCategory}
+      {#snippet categoryContent()}
+        {#if data.doc?.contentNodes}
+          <MdxContent nodes={data.doc.contentNodes} components={mdxComponents} />
+        {:else if data.doc?.content}
+          {@html data.doc.content}
+        {/if}
+      {/snippet}
+      <CategoryIndex
+        categoryPath={data.slug}
+        version={data.version}
+        allDocs={allDocsCompat}
+        title={data.doc.meta.title}
+        description={data.doc.meta.description}
+        content={categoryContent}
+        config={data.config}
+      />
+    {:else}
+      <SearchHighlight />
+      <DocLayout
+        meta={data.doc.meta}
+        previousDoc={previousDoc}
+        nextDoc={nextDoc}
+        version={data.version}
+        slug={data.slug}
+        product={data.product}
+        config={data.config}
+      >
+        {#if data.doc.contentNodes}
+          <MdxContent nodes={data.doc.contentNodes} components={mdxComponents} />
+        {:else}
+          {@html data.doc.content}
+        {/if}
+      </DocLayout>
+    {/if}
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{/if}

package/templates/minimal/src/routes/docs/[version]/+layout.server.ts

@@ -0,0 +1,42 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, getProducts, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { version } = params;
+
+  // Route disambiguation: if this "version" is actually a product slug,
+  // the +page.server.ts will handle the redirect. The layout still needs
+  // to return data for the version case.
+  const products = getProducts();
+  const isProduct = products.some(p => p.slug === version);
+  if (isProduct) {
+    // Return minimal data — the page will redirect before rendering
+    return { allDocs: [], versions: [], versionsMeta: [], config: getEffectiveConfig(''), products };
+  }
+
+  const i18nConfig = getI18nConfig();
+  const defaultLocale = i18nConfig?.defaultLocale || 'en';
+
+  // Block access to hidden versions — redirect to active version
+  const currentVersionConfig = loadVersionConfig(version);
+  if (currentVersionConfig?.hidden) {
+    const config = getEffectiveConfig(version);
+    const activeVersion = config.site?.activeVersion || 'v1.0.0';
+    throw redirect(302, `/docs/${activeVersion}`);
+  }
+
+  const allDocs = await getCachedAllDocs(version, defaultLocale);
+  const versions = getCachedVersions();
+  const config = getEffectiveConfig(version);
+  const versionsMeta = getVersionsMeta(versions);
+
+  return {
+    allDocs,
+    versions,
+    versionsMeta,
+    config,
+    products,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

package/templates/minimal/src/routes/docs/[version]/+page.server.ts

@@ -0,0 +1,27 @@
+import { redirect } from '@sveltejs/kit';
+import { getCachedVersions, getCachedAllDocs, getProducts, getEffectiveConfig } from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { version } = params;
+
+  // Route disambiguation: check if this "version" is actually a product slug
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === version);
+  if (matchedProduct) {
+    // This is /docs/{product} — redirect to the product's active version
+    const config = getEffectiveConfig('', version);
+    const activeVersion = matchedProduct.config.activeVersion || config.site?.activeVersion || 'v1.0.0';
+    redirect(302, `/docs/${version}/${activeVersion}`);
+  }
+
+  // Standard version route
+  const docs = await getCachedAllDocs(version);
+
+  if (docs.length === 0) {
+    redirect(302, '/docs/v1.0.0');
+  }
+
+  // Redirect to first doc
+  redirect(302, `/docs/${version}/${docs[0].slug}`);
+};