specra-cli 0.3.0

package/templates/minimal/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/minimal/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/minimal/static/api-specs/openapi-example.json

@@ -0,0 +1,259 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "User Management API",
+    "version": "1.0.0",
+    "description": "A simple API for managing users (OpenAPI format example)"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com/v1",
+      "description": "Production server"
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "JWT Bearer token authentication"
+      }
+    },
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "example": "user_123"
+          },
+          "name": {
+            "type": "string",
+            "example": "John Doe"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "example": "john@example.com"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "example": "2024-01-15T10:30:00Z"
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string"
+          },
+          "code": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ],
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List all users",
+        "description": "Retrieve a paginated list of all users",
+        "operationId": "listUsers",
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "description": "Page number for pagination",
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "example": 1
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Number of items per page",
+            "schema": {
+              "type": "integer",
+              "default": 10,
+              "example": 10
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of users retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/User"
+                  }
+                },
+                "example": [
+                  {
+                    "id": "user_123",
+                    "name": "John Doe",
+                    "email": "john@example.com",
+                    "createdAt": "2024-01-15T10:30:00Z"
+                  },
+                  {
+                    "id": "user_456",
+                    "name": "Jane Smith",
+                    "email": "jane@example.com",
+                    "createdAt": "2024-01-16T14:20:00Z"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a new user",
+        "description": "Create a new user account",
+        "operationId": "createUser",
+        "requestBody": {
+          "description": "User data to create",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["name", "email"],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "example": "John Doe"
+                  },
+                  "email": {
+                    "type": "string",
+                    "format": "email",
+                    "example": "john@example.com"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "User created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request data",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "example": {
+                  "error": "Email already exists",
+                  "code": "DUPLICATE_EMAIL"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/{id}": {
+      "get": {
+        "summary": "Get user by ID",
+        "description": "Retrieve a single user by their unique identifier",
+        "operationId": "getUserById",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The user's unique identifier",
+            "schema": {
+              "type": "string",
+              "example": "user_123"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "User not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "example": {
+                  "error": "User not found",
+                  "code": "USER_NOT_FOUND"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a user",
+        "description": "Permanently delete a user account",
+        "operationId": "deleteUser",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The user's unique identifier",
+            "schema": {
+              "type": "string",
+              "example": "user_123"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "User deleted successfully"
+          },
+          "404": {
+            "description": "User not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "example": {
+                  "error": "User not found",
+                  "code": "USER_NOT_FOUND"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}