specra-cli 0.3.0

package/templates/book-docs/docs/v2.0.0/customization/themes.mdx

@@ -0,0 +1,81 @@
+---
+title: Themes
+description: Configure the look and feel of your documentation site
+sidebar_position: 1
+---
+
+The platform supports light and dark themes out of the box, with full control over which mode is used by default.
+
+## Theme Modes
+
+Three theme modes are available:
+
+| Mode | Description |
+|------|-------------|
+| `light` | Always use the light theme |
+| `dark` | Always use the dark theme |
+| `system` | Follow the user's operating system preference |
+
+## Configuration
+
+Set the default theme in `specra.config.json`:
+
+```json
+{
+  "theme": {
+    "defaultMode": "dark",
+    "respectPrefersColorScheme": true
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultMode` | `"light" \| "dark" \| "system"` | `"system"` | Initial theme mode |
+| `respectPrefersColorScheme` | `boolean` | `true` | Whether to detect and follow OS preference |
+
+<Callout type="info">
+  When `respectPrefersColorScheme` is `true` and `defaultMode` is `"system"`, the site automatically switches themes when the user changes their OS appearance settings.
+</Callout>
+
+## Theme Toggle
+
+Users can switch themes using the toggle button in the site header. Their preference is saved in local storage and persists across visits.
+
+## Customizing Colors
+
+All colors are defined as CSS custom properties, making them easy to override:
+
+```css
+:root {
+  --primary: oklch(0.55 0.22 264.376);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+}
+
+.dark {
+  --primary: oklch(0.65 0.22 264.376);
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.95 0 0);
+}
+```
+
+<Callout type="tip">
+  Use the OKLCH color space for perceptually uniform color adjustments. This ensures colors look consistent across light and dark themes.
+</Callout>
+
+## Best Practices
+
+<Steps>
+  <Step title="Choose a Default">
+    Pick a default theme that matches your brand. For developer documentation, dark mode is often preferred.
+  </Step>
+
+  <Step title="Test Both Themes">
+    Always preview your content in both light and dark modes. Ensure images, diagrams, and code blocks are readable in both.
+  </Step>
+
+  <Step title="Respect User Preference">
+    Keep `respectPrefersColorScheme` enabled so users get the theme they expect.
+  </Step>
+</Steps>

package/templates/book-docs/docs/v2.0.0/introduction.mdx

@@ -0,0 +1,39 @@
+---
+title: Introduction
+description: Welcome to the documentation
+sidebar_position: 1
+icon: book
+---
+
+Welcome to the v2 documentation. This knowledge base covers everything you need to get started, create content, and customize your site.
+
+## Quick Links
+
+<CardGrid cols={2}>
+  <Card icon="zap" title="Quick Start" description="Get up and running in under 5 minutes" href="/docs/v2.0.0/quickstart" />
+  <Card icon="book-open" title="Core Concepts" description="Understand the key ideas behind the platform" href="/docs/v2.0.0/concepts" />
+  <Card icon="file-text" title="Content Guide" description="Learn how to write and organize content" href="/docs/v2.0.0/content/formatting" />
+  <Card icon="palette" title="Customization" description="Themes, branding, and design options" href="/docs/v2.0.0/customization/themes" />
+</CardGrid>
+
+## Overview
+
+This documentation platform gives you a modern, fast, and beautiful docs experience out of the box. In v2 we've improved performance and added new customization options.
+
+- **Versioned documentation** — maintain docs for multiple releases
+- **Dark and light themes** — automatic or manual switching
+- **Rich components** — callouts, tabs, code blocks, cards, and more
+- **Sidebar navigation** — auto-generated from your file structure
+- **Full-text search** — find anything instantly
+
+<Callout type="tip">
+  Use the sidebar to navigate between sections, or use the search bar to find specific topics.
+</Callout>
+
+## What's New in v2
+
+| Feature | Description |
+|---------|-------------|
+| **Improved Performance** | Faster page loads and smaller bundle sizes |
+| **New Customization** | More control over themes and branding |
+| **Better Navigation** | Enhanced sidebar and breadcrumb experience |

package/templates/book-docs/docs/v2.0.0/quickstart.mdx

@@ -0,0 +1,112 @@
+---
+title: Quick Start
+description: Get up and running in under 5 minutes
+sidebar_position: 2
+icon: zap
+---
+
+Follow these steps to set up your documentation site and start writing content.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Node.js 18+** installed
+- A package manager (**npm**, **yarn**, or **pnpm**)
+
+## Installation
+
+<Steps>
+  <Step title="Create a New Project">
+    Run the CLI to scaffold a new documentation site:
+
+    ```bash
+    npx create-specra my-docs
+    ```
+  </Step>
+
+  <Step title="Install Dependencies">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+cd my-docs && npm install
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+cd my-docs && yarn install
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+cd my-docs && pnpm install
+```
+      </Tab>
+    </Tabs>
+  </Step>
+
+  <Step title="Start the Dev Server">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+npm run dev
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+yarn dev
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+pnpm dev
+```
+      </Tab>
+    </Tabs>
+
+    Your docs site is now running at `http://localhost:5173`.
+  </Step>
+</Steps>
+
+## Project Structure
+
+After scaffolding, your project looks like this:
+
+```txt
+my-docs/
+├── docs/
+│   ├── v1.0.0/          # Previous version docs
+│   └── v2.0.0/          # Current version docs
+├── src/                  # SvelteKit application
+├── specra.config.json    # Site configuration
+└── package.json
+```
+
+<Callout type="info">
+  All documentation lives in the `docs/` directory as `.mdx` files. The sidebar is automatically generated from the folder structure.
+</Callout>
+
+## Creating Your First Page
+
+Create a new file at `docs/v2.0.0/my-page.mdx`:
+
+```mdx
+---
+title: My First Page
+description: A page I just created
+sidebar_position: 10
+---
+
+# Hello World
+
+This is my first documentation page.
+```
+
+Save the file and it will appear in the sidebar automatically.
+
+## Next Steps
+
+<CardGrid cols={2}>
+  <Card icon="lightbulb" title="Core Concepts" description="Learn the key ideas" href="/docs/v2.0.0/concepts" />
+  <Card icon="file-text" title="Formatting" description="Style your content" href="/docs/v2.0.0/content/formatting" />
+</CardGrid>

package/templates/book-docs/gitignore

@@ -0,0 +1,7 @@
+node_modules
+.svelte-kit
+build
+.env
+.env.*
+!.env.example
+vite.config.ts.timestamp-*

package/templates/book-docs/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "my-docs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "specra": "^0.2.4"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.0",
+    "@sveltejs/kit": "^2.0.0",
+    "@sveltejs/vite-plugin-svelte": "^6.0.0",
+    "@tailwindcss/postcss": "^4.1.9",
+    "@tailwindcss/typography": "^0.5.19",
+    "postcss": "^8.5",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "tailwindcss": "^4.1.9",
+    "typescript": "^5",
+    "vite": "^6.3.0"
+  }
+}

package/templates/book-docs/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
+
+export default config

package/templates/book-docs/public/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"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}