create-specra 0.2.2 → 0.2.5

package/templates/book-docs/src/app.css

@@ -1,7 +1,86 @@
 @import "specra/styles";
 @source "./**/*.{js,ts,svelte}";
 
-@theme {
+@theme inline {
     --font-sans: "Geist", "Geist Fallback", system-ui, sans-serif;
     --font-mono: "Geist Mono", "Geist Mono Fallback", monospace;
 }
+
+/* =============================================
+   THEME OVERRIDES
+   Uncomment a :root block for light theme and/or
+   a .dark block for dark theme. Mix and match!
+   ============================================= */
+
+/* ─── Mint Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 162);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 162);
+} */
+
+/* ─── Ocean Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 240);
+} */
+
+/* ─── Rose Light ─── */
+/* :root {
+  --primary: oklch(0.50 0.20 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.50 0.20 350);
+} */
+
+/* ─── Amber Light ─── */
+/* :root {
+  --primary: oklch(0.55 0.16 70);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.55 0.16 70);
+} */
+
+/* ─── Violet Light ─── */
+/* :root {
+  --primary: oklch(0.48 0.22 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.48 0.22 290);
+} */
+
+/* ─── Mint Dark ─── */
+/* .dark {
+  --primary: oklch(0.72 0.18 162);
+  --primary-foreground: oklch(0.10 0.03 160);
+  --ring: oklch(0.72 0.18 162);
+} */
+
+/* ─── Ocean Dark ─── */
+/* .dark {
+  --primary: oklch(0.68 0.16 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.68 0.16 240);
+} */
+
+/* ─── Rose Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.18 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.18 350);
+} */
+
+/* ─── Amber Dark ─── */
+/* .dark {
+  --primary: oklch(0.75 0.16 70);
+  --primary-foreground: oklch(0.10 0.03 70);
+  --ring: oklch(0.75 0.16 70);
+} */
+
+/* ─── Violet Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.20 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.20 290);
+} */
+
+/* For full theme customization (backgrounds, borders, sidebar, etc.)
+   see: https://specra-docs.com/docs/v1.0.0/configuration/theming */

package/templates/book-docs/src/routes/+layout.server.ts

@@ -5,6 +5,9 @@ import type { SpecraConfig } from 'specra';
 
 initConfig(specraConfig as unknown as Partial<SpecraConfig>);
 
+export const prerender = true;
+export const trailingSlash = 'never';
+
 export const load: LayoutServerLoad = async () => {
   const config = getConfig();
   return { config };

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

@@ -0,0 +1,31 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { version } = params;
+
+  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,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

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

@@ -2,28 +2,17 @@ import {
   extractTableOfContents,
   getAdjacentDocs,
   isCategoryPage,
-  getCachedVersions,
   getCachedAllDocs,
   getCachedDocBySlug,
   getI18nConfig,
-  getConfig,
 } from 'specra';
 import type { PageServerLoad } from './$types';
 
-export const load: PageServerLoad = async ({ params }) => {
+export const load: PageServerLoad = async ({ params, parent }) => {
   const { version, slug: slugArray } = params;
-  const slug = slugArray;
+  const slug = slugArray.replace(/\/$/, '');
+  const { allDocs, versions, config, versionsMeta, versionBanner } = await parent();
 
-  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 versions = getCachedVersions();
-  const config = getConfig();
   const isCategory = isCategoryPage(slug, allDocs);
   const doc = await getCachedDocBySlug(slug, version);
 
@@ -51,6 +40,8 @@ export const load: PageServerLoad = async ({ params }) => {
       slug,
       allDocs,
       versions,
+      versionsMeta,
+      versionBanner,
       config,
       isCategory: true,
       isNotFound: false,
@@ -74,6 +65,8 @@ export const load: PageServerLoad = async ({ params }) => {
       slug,
       allDocs,
       versions,
+      versionsMeta,
+      versionBanner,
       config,
       isCategory: false,
       isNotFound: true,
@@ -102,6 +95,8 @@ export const load: PageServerLoad = async ({ params }) => {
     slug,
     allDocs,
     versions,
+    versionsMeta,
+    versionBanner,
     config,
     isCategory: showCategoryIndex,
     isNotFound: false,

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

@@ -2,6 +2,7 @@
   import {
     TableOfContents,
     Header,
+    TabGroups,
     DocLayout,
     CategoryIndex,
     HotReloadIndicator,
@@ -44,7 +45,19 @@
     activeTabGroup={data.categoryTabGroup}
   >
     {#snippet header()}
-      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config}>
+        {#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}
@@ -65,7 +78,19 @@
     config={data.config}
   >
     {#snippet header()}
-      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config}>
+        {#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>
@@ -80,7 +105,19 @@
     activeTabGroup={data.categoryTabGroup}
   >
     {#snippet header()}
-      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config}>
+        {#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}

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

@@ -1,8 +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 }
+  vitePreprocess: { vitePreprocess },
+  kit: {
+    adapter: adapter(),
+    prerender: { handleHttpError: 'warn', handleMissingId: 'warn' }
+  }
 });
 
 export default config;

package/templates/jbrains-docs/.env.sample

@@ -0,0 +1 @@
+SPECTRA_TOKEN=sk_xxx...

package/templates/jbrains-docs/package.json

@@ -10,10 +10,10 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
   },
   "dependencies": {
-    "specra": "^0.2.1"
+    "specra": "^0.2.4"
   },
   "devDependencies": {
-    "@sveltejs/adapter-auto": "^3.0.0",
+    "@sveltejs/adapter-static": "^3.0.0",
     "@sveltejs/kit": "^2.0.0",
     "@sveltejs/vite-plugin-svelte": "^6.0.0",
     "@tailwindcss/postcss": "^4.1.9",

package/templates/jbrains-docs/src/app.css

@@ -1,7 +1,86 @@
 @import "specra/styles";
 @source "./**/*.{js,ts,svelte}";
 
-@theme {
+@theme inline {
     --font-sans: "Geist", "Geist Fallback", system-ui, sans-serif;
     --font-mono: "Geist Mono", "Geist Mono Fallback", monospace;
 }
+
+/* =============================================
+   THEME OVERRIDES
+   Uncomment a :root block for light theme and/or
+   a .dark block for dark theme. Mix and match!
+   ============================================= */
+
+/* ─── Mint Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 162);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 162);
+} */
+
+/* ─── Ocean Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 240);
+} */
+
+/* ─── Rose Light ─── */
+/* :root {
+  --primary: oklch(0.50 0.20 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.50 0.20 350);
+} */
+
+/* ─── Amber Light ─── */
+/* :root {
+  --primary: oklch(0.55 0.16 70);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.55 0.16 70);
+} */
+
+/* ─── Violet Light ─── */
+/* :root {
+  --primary: oklch(0.48 0.22 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.48 0.22 290);
+} */
+
+/* ─── Mint Dark ─── */
+/* .dark {
+  --primary: oklch(0.72 0.18 162);
+  --primary-foreground: oklch(0.10 0.03 160);
+  --ring: oklch(0.72 0.18 162);
+} */
+
+/* ─── Ocean Dark ─── */
+/* .dark {
+  --primary: oklch(0.68 0.16 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.68 0.16 240);
+} */
+
+/* ─── Rose Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.18 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.18 350);
+} */
+
+/* ─── Amber Dark ─── */
+/* .dark {
+  --primary: oklch(0.75 0.16 70);
+  --primary-foreground: oklch(0.10 0.03 70);
+  --ring: oklch(0.75 0.16 70);
+} */
+
+/* ─── Violet Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.20 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.20 290);
+} */
+
+/* For full theme customization (backgrounds, borders, sidebar, etc.)
+   see: https://specra-docs.com/docs/v1.0.0/configuration/theming */

package/templates/jbrains-docs/src/routes/+layout.server.ts

@@ -5,6 +5,9 @@ import type { SpecraConfig } from 'specra';
 
 initConfig(specraConfig as unknown as Partial<SpecraConfig>);
 
+export const prerender = true;
+export const trailingSlash = 'always';
+
 export const load: LayoutServerLoad = async () => {
   const config = getConfig();
   return { config };

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

@@ -0,0 +1,31 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { version } = params;
+
+  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,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

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

@@ -2,28 +2,17 @@ import {
   extractTableOfContents,
   getAdjacentDocs,
   isCategoryPage,
-  getCachedVersions,
   getCachedAllDocs,
   getCachedDocBySlug,
   getI18nConfig,
-  getConfig,
 } from 'specra';
 import type { PageServerLoad } from './$types';
 
-export const load: PageServerLoad = async ({ params }) => {
+export const load: PageServerLoad = async ({ params, parent }) => {
   const { version, slug: slugArray } = params;
-  const slug = slugArray;
+  const slug = slugArray.replace(/\/$/, '');
+  const { allDocs, versions, config, versionsMeta, versionBanner } = await parent();
 
-  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 versions = getCachedVersions();
-  const config = getConfig();
   const isCategory = isCategoryPage(slug, allDocs);
   const doc = await getCachedDocBySlug(slug, version);
 
@@ -51,6 +40,8 @@ export const load: PageServerLoad = async ({ params }) => {
       slug,
       allDocs,
       versions,
+      versionsMeta,
+      versionBanner,
       config,
       isCategory: true,
       isNotFound: false,
@@ -74,6 +65,8 @@ export const load: PageServerLoad = async ({ params }) => {
       slug,
       allDocs,
       versions,
+      versionsMeta,
+      versionBanner,
       config,
       isCategory: false,
       isNotFound: true,
@@ -102,6 +95,8 @@ export const load: PageServerLoad = async ({ params }) => {
     slug,
     allDocs,
     versions,
+    versionsMeta,
+    versionBanner,
     config,
     isCategory: showCategoryIndex,
     isNotFound: false,

package/templates/jbrains-docs/src/routes/docs/[version]/[...slug]/+page.svelte

@@ -2,6 +2,7 @@
   import {
     TableOfContents,
     Header,
+    TabGroups,
     DocLayout,
     CategoryIndex,
     HotReloadIndicator,
@@ -44,7 +45,19 @@
     activeTabGroup={data.categoryTabGroup}
   >
     {#snippet header()}
-      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config}>
+        {#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}
@@ -65,7 +78,19 @@
     config={data.config}
   >
     {#snippet header()}
-      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config}>
+        {#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>
@@ -80,7 +105,19 @@
     activeTabGroup={data.categoryTabGroup}
   >
     {#snippet header()}
-      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config}>
+        {#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}

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

@@ -1,8 +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 }
+  vitePreprocess: { vitePreprocess },
+  kit: {
+    adapter: adapter(),
+    prerender: { handleHttpError: 'warn', handleMissingId: 'warn' }
+  }
 });
 
 export default config;

package/templates/minimal/.env.sample

@@ -0,0 +1 @@
+SPECTRA_TOKEN=sk_xxx...

package/templates/minimal/package.json

@@ -10,7 +10,7 @@
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
   },
   "dependencies": {
-    "specra": "^0.2.1"
+    "specra": "^0.2.4"
   },
   "devDependencies": {
     "@sveltejs/adapter-static": "^3.0.0",

package/templates/minimal/src/app.css

@@ -1,7 +1,86 @@
 @import "specra/styles";
 @source "./**/*.{js,ts,svelte}";
 
-@theme {
+@theme inline {
     --font-sans: "Geist", "Geist Fallback", system-ui, sans-serif;
     --font-mono: "Geist Mono", "Geist Mono Fallback", monospace;
 }
+
+/* =============================================
+   THEME OVERRIDES
+   Uncomment a :root block for light theme and/or
+   a .dark block for dark theme. Mix and match!
+   ============================================= */
+
+/* ─── Mint Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 162);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 162);
+} */
+
+/* ─── Ocean Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 240);
+} */
+
+/* ─── Rose Light ─── */
+/* :root {
+  --primary: oklch(0.50 0.20 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.50 0.20 350);
+} */
+
+/* ─── Amber Light ─── */
+/* :root {
+  --primary: oklch(0.55 0.16 70);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.55 0.16 70);
+} */
+
+/* ─── Violet Light ─── */
+/* :root {
+  --primary: oklch(0.48 0.22 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.48 0.22 290);
+} */
+
+/* ─── Mint Dark ─── */
+/* .dark {
+  --primary: oklch(0.72 0.18 162);
+  --primary-foreground: oklch(0.10 0.03 160);
+  --ring: oklch(0.72 0.18 162);
+} */
+
+/* ─── Ocean Dark ─── */
+/* .dark {
+  --primary: oklch(0.68 0.16 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.68 0.16 240);
+} */
+
+/* ─── Rose Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.18 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.18 350);
+} */
+
+/* ─── Amber Dark ─── */
+/* .dark {
+  --primary: oklch(0.75 0.16 70);
+  --primary-foreground: oklch(0.10 0.03 70);
+  --ring: oklch(0.75 0.16 70);
+} */
+
+/* ─── Violet Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.20 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.20 290);
+} */
+
+/* For full theme customization (backgrounds, borders, sidebar, etc.)
+   see: https://specra-docs.com/docs/v1.0.0/configuration/theming */

package/templates/minimal/src/routes/+layout.server.ts

@@ -6,7 +6,7 @@ import type { SpecraConfig } from 'specra';
 initConfig(specraConfig as unknown as Partial<SpecraConfig>);
 
 export const prerender = true;
-export const trailingSlash = 'always';
+export const trailingSlash = 'never';
 
 export const load: LayoutServerLoad = async () => {
   const config = getConfig();