specra-cli 0.3.0

package/templates/book-docs/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/book-docs/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/book-docs/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/book-docs/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}`);
+};

package/templates/book-docs/src/routes/docs/[version]/[...slug]/+page.server.ts

@@ -0,0 +1,106 @@
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getI18nConfig,
+} from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { version, slug: slugArray } = params;
+  const slug = slugArray.replace(/\/$/, '');
+
+  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);
+  const isCategory = isCategoryPage(slug, allDocs);
+  const doc = await getCachedDocBySlug(slug, version);
+
+  let title = 'Page Not Found';
+  let description = 'The requested documentation page could not be found.';
+  let ogUrl = `/docs/${version}/${slug}`;
+
+  if (doc) {
+    title = doc.meta.title || doc.title;
+    description = doc.meta.description || `Documentation for ${title}`;
+  }
+
+  // Category page without doc content
+  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,
+      isCategory: true,
+      isNotFound: false,
+      doc: null,
+      categoryTitle,
+      categoryDescription: 'Browse the documentation in this section.',
+      categoryTabGroup,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+
+  // Not found
+  if (!doc) {
+    return {
+      version,
+      slug,
+      isCategory: false,
+      isNotFound: true,
+      doc: null,
+      categoryTitle: null,
+      categoryDescription: null,
+      categoryTabGroup: undefined,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+
+  // Normal doc page
+  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,
+    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/book-docs/src/routes/docs/[version]/[...slug]/+page.svelte

@@ -0,0 +1,172 @@
+<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}
+    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}>
+        {#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}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    <CategoryIndex
+      categoryPath={data.slug}
+      version={data.version}
+      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}
+    config={data.config}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products}>
+        {#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}
+              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}
+    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}>
+        {#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}
+              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}
+        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/book-docs/static/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#6366f1"/>
+  <text x="16" y="23" font-family="system-ui,sans-serif" font-size="20" font-weight="bold" fill="white" text-anchor="middle">S</text>
+</svg>

package/templates/book-docs/svelte.config.js

@@ -0,0 +1,13 @@
+import adapter from '@sveltejs/adapter-static';
+import { specraConfig } from 'specra/svelte-config';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+const config = specraConfig({
+  vitePreprocess: { vitePreprocess },
+  kit: {
+    adapter: adapter(),
+    prerender: { handleHttpError: 'warn', handleMissingId: 'warn', handleUnseenRoutes: 'warn' }
+  }
+});
+
+export default config;

package/templates/book-docs/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./.svelte-kit/tsconfig.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}