create-specra 0.2.3 → 0.2.5

package/README.md

@@ -2,6 +2,17 @@
 
 The fastest way to create a new Specra documentation site. Scaffold a complete documentation project with a single command.
 
+## What is Specra?
+
+Specra is a modern documentation library for SvelteKit that provides:
+- Multi-version documentation support
+- API reference generation
+- Full-text search
+- MDX-powered content
+- Beautiful UI components
+
+The official Specra site ([specra-docs](https://specra-docs.com)) also offers a SaaS platform with paid tiers (Starter, Pro, Enterprise) including authentication, Stripe/M-Pesa billing, and a user dashboard. The CLI scaffolds free, self-hosted documentation sites — no billing features are included in generated projects.
+
 ## Usage
 
 ### With npx (recommended)
@@ -142,16 +153,81 @@ Once your project is created, you can:
 
 4. Customize your site in `specra.config.json`
 
-## What is Specra?
+## Deployment
 
-Specra is a modern documentation library for SvelteKit that provides:
-- Multi-version documentation support
-- API reference generation
-- Full-text search
-- MDX-powered content
-- Beautiful UI components
+Specra projects are standard SvelteKit apps, so you can deploy anywhere SvelteKit runs.
 
-The official Specra site ([specra-docs](https://specra-docs.com)) also offers a SaaS platform with paid tiers (Starter, Pro, Enterprise) including authentication, Stripe/M-Pesa billing, and a user dashboard. The CLI scaffolds free, self-hosted documentation sites — no billing features are included in generated projects.
+### Static Hosting (Vercel, Netlify, Cloudflare Pages)
+
+Install the appropriate SvelteKit adapter:
+
+```bash
+# Vercel
+npm install -D @sveltejs/adapter-vercel
+
+# Netlify
+npm install -D @sveltejs/adapter-netlify
+
+# Cloudflare Pages
+npm install -D @sveltejs/adapter-cloudflare
+```
+
+Update `svelte.config.js` to use the adapter:
+
+```js
+import adapter from '@sveltejs/adapter-vercel'; // or adapter-netlify, etc.
+
+export default {
+  kit: {
+    adapter: adapter()
+  }
+};
+```
+
+Then push to your Git provider — the platform handles the rest.
+
+### Node Server (VPS, Docker, Railway)
+
+Use `@sveltejs/adapter-node` (included by default):
+
+```bash
+npm run build
+node build
+```
+
+The server listens on port 3000 by default. Configure with environment variables:
+
+```bash
+PORT=8080 HOST=0.0.0.0 node build
+```
+
+### Static Site Generation
+
+For fully static docs with no server needed:
+
+```bash
+npm install -D @sveltejs/adapter-static
+```
+
+Update `svelte.config.js`:
+
+```js
+import adapter from '@sveltejs/adapter-static';
+
+export default {
+  kit: {
+    adapter: adapter({
+      fallback: '404.html'
+    })
+  }
+};
+```
+
+```bash
+npm run build
+```
+
+Upload the `build/` directory to any static host (GitHub Pages, S3, etc.).
 
 ## Learn More
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-specra",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CLI tool to scaffold a new Specra documentation site with Next.js",
   "type": "module",
   "bin": {

package/templates/book-docs/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/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

@@ -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();

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.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/jbrains-docs/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/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/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.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/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();

package/templates/minimal/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/minimal/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.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/minimal/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}