specra-cli 0.3.0

package/templates/minimal/docs/v2.0.0/about.mdx

@@ -0,0 +1,57 @@
+---
+title: About Specra
+sidebar_position: 1
+icon: info
+---
+
+Specra is a self-hosted, Mintlify-quality documentation platform built with **SvelteKit**, **MDX**, and **Tailwind CSS**. It provides a polished, readable docs experience with powerful features for both readers and writers.
+
+## Why Specra?
+
+<CardGrid cols={2}>
+  <Card icon="zap" title="Fast & Static" description="Pre-rendered pages with edge caching for lightning-fast load times" />
+  <Card icon="search" title="Instant Search" description="Meilisearch-powered full-text search with typo tolerance" />
+  <Card icon="git-branch" title="Versioned Docs" description="Multiple documentation versions under /docs/v1.0.0/, /docs/v2.0.0/" />
+  <Card icon="palette" title="Theme Support" description="Dark mode, customizable colors, and design tokens" />
+</CardGrid>
+
+## Built With
+
+- **SvelteKit** - Svelte framework with file-based routing
+- **MDX** - Markdown with Svelte components
+- **Tailwind CSS** - Utility-first styling
+- **Meilisearch** - Fast, typo-tolerant search
+- **TypeScript** - Full type safety
+
+## Core Principles
+
+<Steps>
+  <Step title="Content First">
+    Your documentation lives in the `docs/` folder as MDX files. The system handles routing, navigation, and rendering automatically.
+  </Step>
+  
+  <Step title="Developer Experience">
+    Edit MDX files, and see changes instantly with hot reload. No complex configuration required.
+  </Step>
+  
+  <Step title="Production Ready">
+    Built-in SEO, accessibility, performance optimization, and CI/CD integration.
+  </Step>
+</Steps>
+
+## What's Included
+
+| Feature | Description |
+|---------|-------------|
+| **MDX Components** | Callouts, tabs, code blocks, cards, accordions, and more |
+| **Sidebar Navigation** | Auto-generated from folder structure with collapsible groups |
+| **Table of Contents** | Auto-generated from headings with scroll tracking |
+| **Version Switcher** | Switch between documentation versions |
+| **Search** | Full-text search with keyboard shortcuts (⌘K) |
+| **Dark Mode** | System-aware theme with manual toggle |
+| **Reading Time** | Automatic reading time estimation |
+| **Responsive** | Mobile-first design that works on all devices |
+
+## Getting Started
+
+Ready to write documentation? Head to the [Getting Started](/docs/v1.0.0/getting-started) guide.

package/templates/minimal/docs/v2.0.0/components/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Components",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "grid",
+  "tab_group": "components"
+}

package/templates/minimal/docs/v2.0.0/components/callout.mdx

@@ -0,0 +1,83 @@
+---
+title: Callout
+description: Highlight important information with styled callout boxes
+sidebar_position: 4
+---
+
+Callouts draw attention to important information within your content. They're styled based on the type of message they convey.
+
+## Usage
+
+```mdx
+<Callout type="info">
+  This is helpful information for the reader.
+</Callout>
+```
+
+## Types
+
+### Info
+<Callout type="info">
+  This provides additional context or helpful tips.
+</Callout>
+
+```mdx
+<Callout type="info">
+  Helpful additional context goes here.
+</Callout>
+```
+
+### Note
+<Callout type="note">
+  Notes highlight important information the reader should be aware of.
+</Callout>
+
+### Tip
+<Callout type="tip">
+  Tips provide suggestions for better usage or best practices.
+</Callout>
+
+### Warning
+<Callout type="warning">
+  Warnings alert users to potential issues or breaking changes.
+</Callout>
+
+### Success
+<Callout type="success">
+  Success callouts confirm positive outcomes or completed actions.
+</Callout>
+
+### Error
+<Callout type="error">
+  Error callouts highlight critical issues or things to avoid.
+</Callout>
+
+### Danger
+<Callout type="danger">
+  Danger callouts warn about potentially destructive actions.
+</Callout>
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Callout content |
+| `type` | `"info" \| "note" \| "tip" \| "warning" \| "success" \| "error" \| "danger"` | `"info"` | Callout style |
+
+## GitHub-Style Alerts
+
+You can also use markdown blockquotes with alert markers:
+
+```mdx
+> [!INFO]
+> This is an info alert using markdown syntax.
+
+> [!WARNING]
+> This is a warning using markdown syntax.
+```
+
+> [!INFO]
+> This is an info alert using markdown syntax.
+
+> [!WARNING]
+> This is a warning alert using markdown syntax.

package/templates/minimal/docs/v2.0.0/components/code-block.mdx

@@ -0,0 +1,103 @@
+---
+title: Code Block
+description: Display syntax-highlighted code with line numbers and copy functionality
+sidebar_position: 6
+---
+
+Code blocks display syntax-highlighted code with line numbers, a copy button, and optional filename headers.
+
+## Usage
+
+Code blocks are automatically created when using fenced code blocks with a language specifier:
+
+````mdx
+```javascript
+const greeting = "Hello, World!";
+console.log(greeting);
+```
+````
+
+## Live Examples
+
+### JavaScript
+
+```javascript
+function fibonacci(n) {
+  if (n <= 1) return n;
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+console.log(fibonacci(10)); // 55
+```
+
+### TypeScript
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function greetUser(user: User): string {
+  return `Hello, ${user.name}!`;
+}
+```
+
+### Python
+
+```python
+def quicksort(arr):
+    if len(arr) <= 1:
+        return arr
+    pivot = arr[len(arr) // 2]
+    left = [x for x in arr if x < pivot]
+    middle = [x for x in arr if x == pivot]
+    right = [x for x in arr if x > pivot]
+    return quicksort(left) + middle + quicksort(right)
+```
+
+### Bash
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+### JSON
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "react": "^19.0.0",
+    "next": "^16.0.0"
+  }
+}
+```
+
+## Features
+
+<Callout type="info">
+Code blocks include automatic syntax highlighting for many languages including JavaScript, TypeScript, Python, Bash, JSON, CSS, and more.
+</Callout>
+
+- **Syntax Highlighting** - Automatic language detection and highlighting
+- **Line Numbers** - Easy reference for specific lines
+- **Copy Button** - One-click code copying
+- **Filename Header** - Optional filename display
+
+## Supported Languages
+
+Common languages include:
+- `javascript`, `typescript`, `jsx`, `tsx`
+- `python`, `ruby`, `go`, `rust`
+- `bash`, `shell`, `powershell`
+- `html`, `css`, `scss`
+- `json`, `yaml`, `toml`
+- `sql`, `graphql`
+- `markdown`, `mdx`

package/templates/minimal/docs/v2.0.0/components/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Components
+description: A comprehensive guide to all available components
+---
+
+### A list of over 10 useful components
+
+Welcome to the components documentation. Here you'll find information about all the reusable components available in this documentation system.

package/templates/minimal/docs/v2.0.0/components/tabs.mdx

@@ -0,0 +1,92 @@
+---
+title: Tabs
+description: Organize content into tabbed sections
+sidebar_position: 15
+---
+
+Tabs organize content into switchable panels, perfect for showing alternatives like different package managers or language examples.
+
+## Usage
+
+```mdx
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+    npm content here
+  </Tab>
+
+  <Tab label="yarn">
+    yarn content here
+  </Tab>
+
+  <Tab label="pnpm">
+    pnpm content here
+  </Tab>
+</Tabs>
+```
+
+## Live Examples
+
+### Package Manager Selection
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm install my-package
+```
+  </Tab>
+
+  <Tab label="yarn">
+```bash
+yarn add my-package
+```
+  </Tab>
+
+  <Tab label="pnpm">
+```bash
+pnpm add my-package
+```
+  </Tab>
+</Tabs>
+
+### Code Examples
+
+<Tabs defaultValue="JavaScript">
+  <Tab label="JavaScript">
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+  </Tab>
+
+  <Tab label="TypeScript">
+```typescript
+function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+```
+  </Tab>
+
+  <Tab label="Python">
+```python
+def greet(name):
+    return f"Hello, {name}!"
+```
+  </Tab>
+</Tabs>
+
+## Props
+
+### Tabs
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Tab components |
+| `defaultValue` | `string` | - | Label of initially selected tab (defaults to first tab) |
+
+### Tab
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | required | Tab button label |
+| `children` | `ReactNode` | required | Content shown when tab is active |

package/templates/minimal/docs/v2.0.0/configuration.mdx

@@ -0,0 +1,322 @@
+---
+title: Configuration
+description: Configure your Specra documentation site with specra.config.json
+sidebar_position: 3
+icon: cog
+tab_group: guides
+---
+
+Specra uses a centralized configuration file `specra.config.json` at the project root to manage all settings.
+
+## Complete Configuration Example
+
+Here's a complete example showing all available configuration options:
+
+```json
+{
+  "$schema": "./lib/config.types.ts",
+  "site": {
+    "title": "Documentation Library",
+    "description": "Comprehensive documentation for your project",
+    "url": "https://your-docs.com",
+    "baseUrl": "/",
+    "language": "en",
+    "organizationName": "Your Organization",
+    "projectName": "your-project",
+    "activeVersion": "v1.0.0",
+    "favicon": "/icon-light-32x32.png"
+  },
+  "theme": {
+    "defaultMode": "system",
+    "respectPrefersColorScheme": true
+  },
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "tocPosition": "right",
+    "tocMaxDepth": 3,
+    "tabGroups": [
+      {
+        "id": "guides",
+        "label": "Guides",
+        "icon": "book-open"
+      },
+      {
+        "id": "api",
+        "label": "API Reference",
+        "icon": "zap"
+      }
+    ]
+  },
+  "social": {
+    "github": "https://github.com/your-org/your-repo",
+    "twitter": "https://twitter.com/your-handle",
+    "discord": "https://discord.gg/your-server",
+    "custom": [
+      {
+        "label": "Website",
+        "href": "https://yourwebsite.com"
+      }
+    ]
+  },
+  "search": {
+    "enabled": true,
+    "placeholder": "Search documentation...",
+    "provider": "meilisearch",
+    "meilisearch": {
+      "host": "http://localhost:7700",
+      "apiKey": "your-api-key",
+      "indexName": "docs"
+    }
+  },
+  "analytics": {
+    "googleAnalytics": "G-XXXXXXXXXX",
+    "plausible": "your-domain.com"
+  },
+  "footer": {
+    "copyright": "Copyright © 2024 Your Organization. All rights reserved.",
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          {
+            "label": "Getting Started",
+            "href": "/docs/v1.0.0/getting-started"
+          },
+          {
+            "label": "API Reference",
+            "href": "/docs/v1.0.0/api-overview"
+          }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          {
+            "label": "GitHub",
+            "href": "https://github.com/your-org/your-repo"
+          },
+          {
+            "label": "Discord",
+            "href": "https://discord.gg/your-server"
+          }
+        ]
+      }
+    ]
+  },
+  "banner": {
+    "enabled": true,
+    "message": "�� Version 2.0 is now available!",
+    "type": "info",
+    "dismissible": true
+  },
+  "features": {
+    "editUrl": "https://github.com/your-org/your-repo/edit/main/docs",
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true,
+    "i18n": false
+  },
+  "env": {
+    "API_BASE_URL": "https://api.example.com",
+    "API_VERSION": "v1",
+    "CDN_URL": "https://cdn.example.com"
+  },
+  "deployment": {
+    "target": "vercel",
+    "basePath": "",
+    "customDomain": false
+  }
+}
+```
+
+<Callout type="tip">
+Copy this complete configuration as a starting point and customize it for your needs.
+</Callout>
+
+## Site Configuration
+
+Core metadata and branding for your documentation site.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title` | string | Site title (shown in header and browser tab) |
+| `description` | string | Meta description for SEO |
+| `url` | string | Full URL where docs are hosted |
+| `baseUrl` | string | Base path (default: `/`) |
+| `language` | string | Language code (default: `en`) |
+| `activeVersion` | string | Default documentation version |
+| `organizationName` | string | Your organization name |
+| `projectName` | string | Project name |
+
+## Theme Configuration
+
+Control the appearance and color scheme.
+
+```json
+{
+  "theme": {
+    "defaultMode": "system",
+    "respectPrefersColorScheme": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `defaultMode` | `"light" \| "dark" \| "system"` | Default theme mode |
+| `respectPrefersColorScheme` | boolean | Follow system theme preference |
+
+## Navigation Configuration
+
+Control sidebar, breadcrumbs, and table of contents.
+
+```json
+{
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "tocPosition": "right",
+    "tocMaxDepth": 3
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `showSidebar` | boolean | Show/hide the sidebar |
+| `collapsibleSidebar` | boolean | Allow sections to collapse |
+| `showBreadcrumbs` | boolean | Show breadcrumb navigation |
+| `showTableOfContents` | boolean | Show table of contents |
+| `tocPosition` | `"left" \| "right"` | TOC position |
+| `tocMaxDepth` | number | Maximum heading depth for TOC (1-6) |
+
+## Search Configuration
+
+Configure the search functionality.
+
+```json
+{
+  "search": {
+    "enabled": true,
+    "placeholder": "Search documentation...",
+    "provider": "meilisearch",
+    "meilisearch": {
+      "host": "http://localhost:7700",
+      "apiKey": "your-api-key",
+      "indexName": "docs"
+    }
+  }
+}
+```
+
+<Callout type="info">
+Press **⌘K** (Mac) or **Ctrl+K** (Windows/Linux) to open the search modal.
+</Callout>
+
+## Social Links
+
+Add links to your social profiles and repositories.
+
+```json
+{
+  "social": {
+    "github": "https://github.com/your-org/your-repo",
+    "twitter": "https://twitter.com/yourhandle",
+    "discord": "https://discord.gg/yourserver"
+  }
+}
+```
+
+## Features Configuration
+
+Toggle documentation features.
+
+```json
+{
+  "features": {
+    "editUrl": "https://github.com/your-org/repo/edit/main/docs",
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `editUrl` | string | Base URL for "Edit this page" links |
+| `showLastUpdated` | boolean | Show last updated date |
+| `showReadingTime` | boolean | Show estimated reading time |
+| `showAuthors` | boolean | Show author information |
+| `showTags` | boolean | Show document tags |
+| `versioning` | boolean | Enable version switcher |
+
+## Environment Variables
+
+Define custom environment variables that can be used in your MDX content:
+
+```json
+{
+  "env": {
+    "API_BASE_URL": "https://api.example.com",
+    "API_VERSION": "v1"
+  }
+}
+```
+
+Use them in MDX with `${VARIABLE_NAME}` or `{{VARIABLE_NAME}}` syntax:
+
+```mdx
+The API is available at ${API_BASE_URL}/users
+```
+
+## Banner Configuration
+
+Show a site-wide banner for announcements.
+
+```json
+{
+  "banner": {
+    "enabled": true,
+    "message": "🎉 Version 2.0 is now available!",
+    "type": "info",
+    "dismissible": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | boolean | Show/hide the banner |
+| `message` | string | Banner message text |
+| `type` | `"info" \| "warning" \| "error"` | Banner style |
+| `dismissible` | boolean | Allow users to dismiss |
+
+## Footer Configuration
+
+Customize the footer links.
+
+```json
+{
+  "footer": {
+    "copyright": "© 2024 Your Organization",
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          { "label": "Getting Started", "href": "/docs/v1.0.0/getting-started" }
+        ]
+      }
+    ]
+  }
+}
+```