create-specra 0.1.7 → 0.2.0

package/templates/jbrains-docs/public/api-specs/users-api.json

@@ -0,0 +1,264 @@
+{
+  "version": "1.0.0",
+  "title": "Users API",
+  "description": "Complete API reference for managing users in the system",
+  "baseUrl": "https://api.example.com/v1",
+  "env": {
+    "AUTH_TOKEN": "your_api_token_here"
+  },
+  "auth": {
+    "type": "bearer",
+    "description": "All requests require a valid API token in the Authorization header",
+    "tokenPrefix": "Bearer"
+  },
+  "globalHeaders": [
+    {
+      "name": "Authorization",
+      "value": "Bearer {AUTH_TOKEN}",
+      "description": "Your API authentication token"
+    },
+    {
+      "name": "Content-Type",
+      "value": "application/json"
+    }
+  ],
+  "endpoints": [
+    {
+      "title": "Get User by ID",
+      "method": "GET",
+      "path": "/users/:id",
+      "description": "Retrieve detailed information about a specific user",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "The unique identifier of the user",
+          "example": "user_123"
+        }
+      ],
+      "queryParams": [
+        {
+          "name": "fields",
+          "type": "string",
+          "description": "Comma-separated list of fields to include",
+          "example": "name,email,created_at"
+        },
+        {
+          "name": "include_metadata",
+          "type": "boolean",
+          "description": "Include additional metadata in the response",
+          "default": false
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "User retrieved successfully",
+        "example": {
+          "id": "user_123",
+          "name": "John Doe",
+          "email": "john@example.com",
+          "role": "admin",
+          "created_at": "2024-01-15T10:30:00Z",
+          "updated_at": "2024-01-20T14:22:00Z"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "User not found",
+          "example": {
+            "error": "User not found",
+            "code": "USER_NOT_FOUND",
+            "message": "No user exists with the provided ID"
+          }
+        },
+        {
+          "status": 401,
+          "description": "Unauthorized",
+          "example": {
+            "error": "Unauthorized",
+            "code": "UNAUTHORIZED",
+            "message": "Invalid or missing authentication token"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X GET \"https://api.example.com/v1/users/user_123\" \\\n  -H \"Authorization: Bearer your_api_token_here\""
+        },
+        {
+          "title": "JavaScript (fetch)",
+          "language": "javascript",
+          "code": "const response = await fetch('https://api.example.com/v1/users/user_123', {\n  headers: {\n    'Authorization': 'Bearer your_api_token_here'\n  }\n});\nconst user = await response.json();"
+        }
+      ]
+    },
+    {
+      "title": "List All Users",
+      "method": "GET",
+      "path": "/users",
+      "description": "Retrieve a paginated list of all users",
+      "queryParams": [
+        {
+          "name": "page",
+          "type": "number",
+          "description": "Page number for pagination",
+          "default": 1
+        },
+        {
+          "name": "limit",
+          "type": "number",
+          "description": "Number of users per page",
+          "default": 20
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "description": "Filter users by role",
+          "example": "admin"
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "List of users retrieved successfully",
+        "example": {
+          "data": [
+            {
+              "id": "user_123",
+              "name": "John Doe",
+              "email": "john@example.com",
+              "role": "admin"
+            },
+            {
+              "id": "user_124",
+              "name": "Jane Smith",
+              "email": "jane@example.com",
+              "role": "user"
+            }
+          ],
+          "pagination": {
+            "page": 1,
+            "limit": 20,
+            "total": 42,
+            "pages": 3
+          }
+        }
+      }
+    },
+    {
+      "title": "Create New User",
+      "method": "POST",
+      "path": "/users",
+      "description": "Create a new user account",
+      "body": {
+        "description": "User data to create",
+        "example": {
+          "name": "Alice Johnson",
+          "email": "alice@example.com",
+          "role": "user",
+          "password": "secure_password_123"
+        }
+      },
+      "successResponse": {
+        "status": 201,
+        "description": "User created successfully",
+        "example": {
+          "id": "user_125",
+          "name": "Alice Johnson",
+          "email": "alice@example.com",
+          "role": "user",
+          "created_at": "2024-01-21T09:15:00Z"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 400,
+          "description": "Validation error",
+          "example": {
+            "error": "Validation failed",
+            "code": "VALIDATION_ERROR",
+            "details": {
+              "email": "Email address already exists"
+            }
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X POST \"https://api.example.com/v1/users\" \\\n  -H \"Authorization: Bearer your_api_token_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Alice Johnson\",\n    \"email\": \"alice@example.com\",\n    \"role\": \"user\",\n    \"password\": \"secure_password_123\"\n  }'"
+        }
+      ]
+    },
+    {
+      "title": "Update User",
+      "method": "PATCH",
+      "path": "/users/:id",
+      "description": "Update user information",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "User ID to update"
+        }
+      ],
+      "body": {
+        "description": "Fields to update (all optional)",
+        "example": {
+          "name": "John Updated",
+          "email": "john.updated@example.com",
+          "role": "moderator"
+        }
+      },
+      "successResponse": {
+        "status": 200,
+        "description": "User updated successfully",
+        "example": {
+          "id": "user_123",
+          "name": "John Updated",
+          "email": "john.updated@example.com",
+          "role": "moderator",
+          "updated_at": "2024-01-21T10:00:00Z"
+        }
+      }
+    },
+    {
+      "title": "Delete User",
+      "method": "DELETE",
+      "path": "/users/:id",
+      "description": "Permanently delete a user account",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "User ID to delete"
+        }
+      ],
+      "successResponse": {
+        "status": 204,
+        "description": "User deleted successfully"
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "User not found"
+        },
+        {
+          "status": 403,
+          "description": "Forbidden - Cannot delete this user",
+          "example": {
+            "error": "Forbidden",
+            "code": "CANNOT_DELETE_ADMIN",
+            "message": "Cannot delete the primary admin account"
+          }
+        }
+      ]
+    }
+  ]
+}

package/templates/jbrains-docs/specra.config.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "./node_modules/specra/config/specra.config.schema.json",
+  "site": {
+    "title": "My Docs",
+    "description": "Documentation for my project",
+    "url": "http://localhost:5173",
+    "baseUrl": "/",
+    "language": "en",
+    "organizationName": "my-org",
+    "projectName": "my-project",
+    "activeVersion": "v1.0.0"
+  },
+  "theme": {
+    "defaultMode": "light",
+    "respectPrefersColorScheme": true
+  },
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "sidebarStyle": "flush",
+    "showBreadcrumbs": true,
+    "showTableOfContents": false,
+    "tocPosition": "right",
+    "tocMaxDepth": 3,
+    "tabGroups": [
+      {
+        "id": "language",
+        "label": "Language"
+      },
+      {
+        "id": "multiplatform",
+        "label": "Multiplatform"
+      }
+    ]
+  },
+  "social": {
+    "github": "https://github.com/your-org/your-repo"
+  },
+  "search": {
+    "enabled": false
+  },
+  "banner": {
+    "enabled": true,
+    "message": "Docs v2.0.0 is now available!",
+    "type": "info",
+    "dismissible": true
+  },
+  "footer": {
+    "copyright": "Copyright © 2025 My Project. All rights reserved.",
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          {
+            "label": "Getting Started",
+            "href": "/docs/v1.0.0/getting-started"
+          }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          {
+            "label": "GitHub",
+            "href": "https://github.com/your-org/your-repo"
+          }
+        ]
+      }
+    ]
+  },
+  "features": {
+    "showLastUpdated": true,
+    "showReadingTime": false,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true,
+    "showVersionBadge": true,
+    "i18n": false
+  }
+}

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

@@ -0,0 +1,2 @@
+@import "specra/styles";
+@source "./**/*.{js,ts,svelte}";

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

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover" class="font-sans antialiased">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

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

@@ -0,0 +1,11 @@
+import { getConfig, initConfig } from 'specra';
+import specraConfig from '../../specra.config.json';
+import type { LayoutServerLoad } from './$types';
+import type { SpecraConfig } from 'specra';
+
+initConfig(specraConfig as unknown as Partial<SpecraConfig>);
+
+export const load: LayoutServerLoad = async () => {
+  const config = getConfig();
+  return { config };
+};

package/templates/jbrains-docs/src/routes/+layout.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import '../app.css';
+  import { LayoutProviders } from 'specra/components';
+  import type { Snippet } from 'svelte';
+  import type { LayoutData } from './$types';
+
+  let { data, children }: { data: LayoutData; children: Snippet } = $props();
+</script>
+
+<svelte:head>
+  <title>{data?.config?.site?.title || 'Documentation'}</title>
+  <meta name="description" content={data?.config?.site?.description || 'Modern documentation platform'} />
+</svelte:head>
+
+{#if data?.config}
+  <LayoutProviders config={data.config}>
+    {@render children?.()}
+  </LayoutProviders>
+{:else}
+  {@render children?.()}
+{/if}

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

@@ -0,0 +1,9 @@
+import { redirect } from '@sveltejs/kit';
+import { getConfig } from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async () => {
+  const config = getConfig();
+  const activeVersion = config.site?.activeVersion || 'v1.0.0';
+  redirect(302, `/docs/${activeVersion}/home`);
+};

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

@@ -0,0 +1,119 @@
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedVersions,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getI18nConfig,
+  getConfig,
+} from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { version, slug: slugArray } = params;
+  const slug = slugArray;
+
+  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);
+
+  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,
+      allDocs,
+      versions,
+      config,
+      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,
+      allDocs,
+      versions,
+      config,
+      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,
+    allDocs,
+    versions,
+    config,
+    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/jbrains-docs/src/routes/docs/[version]/[...slug]/+page.svelte

@@ -0,0 +1,129 @@
+<script lang="ts">
+  import {
+    TableOfContents,
+    Header,
+    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:type" content="article" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content={data.title} />
+  <meta name="twitter:description" content={data.description} />
+</svelte:head>
+
+{#if !data.doc && data.isCategory}
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    config={data.config}
+    activeTabGroup={data.categoryTabGroup}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+    {/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}
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    config={data.config}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+    {/snippet}
+    <NotFoundContent version={data.version} />
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{:else if data.doc}
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    config={data.config}
+    activeTabGroup={data.categoryTabGroup}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} config={data.config} />
+    {/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/jbrains-docs/svelte.config.js

@@ -0,0 +1,8 @@
+import { specraConfig } from 'specra/svelte-config';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+const config = specraConfig({
+  vitePreprocess: { vitePreprocess }
+});
+
+export default config;

package/templates/jbrains-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
+  }
+}

package/templates/jbrains-docs/vite.config.ts

@@ -0,0 +1,6 @@
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [sveltekit()]
+});