specra-cli 0.3.0

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

@@ -0,0 +1,197 @@
+---
+title: Features
+description: Explore all the features of the Specra documentation platform
+sidebar_position: 4
+icon: scroll-text
+---
+
+## Content Features
+
+### MDX Support
+
+Write documentation in MDX—Markdown with React components built in.
+
+```mdx
+# Hello World
+
+This is **Markdown** with a <Badge variant="success">React component</Badge>!
+```
+
+<Callout type="tip">
+MDX lets you create interactive, dynamic documentation that goes beyond static text.
+</Callout>
+
+### Syntax Highlighting
+
+Code blocks automatically get syntax highlighting with line numbers:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function greetUser(user: User): string {
+  return `Hello, ${user.name}!`;
+}
+```
+
+Supported languages include JavaScript, TypeScript, Python, Bash, JSON, CSS, and many more.
+
+### Math Equations
+
+Render mathematical equations using KaTeX:
+
+Inline: <Math>{"E = mc^2"}</Math>
+
+Block:
+<Math block>
+  {"\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}"}
+</Math>
+
+### Mermaid Diagrams
+
+Create diagrams from text using Mermaid:
+
+<Mermaid
+  chart={`
+    graph LR
+      A[Write MDX] --> B[Build]
+      B --> C[Deploy]
+      C --> D[Users Read Docs]
+  `}
+  caption="Documentation workflow"
+/>
+
+## Navigation Features
+
+### Automatic Sidebar
+
+The sidebar is automatically generated from your folder structure. Use `_category_.json` to customize:
+
+```json
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+### Table of Contents
+
+A floating table of contents is automatically generated from your headings. It highlights the current section as you scroll.
+
+### Breadcrumbs
+
+Breadcrumb navigation helps users understand their location in the documentation hierarchy.
+
+### Version Switcher
+
+Support multiple documentation versions with easy switching:
+
+- `/docs/v1.0.0/getting-started`
+- `/docs/v2.0.0/getting-started`
+- `/docs/next/getting-started` (unreleased)
+
+## Search
+
+### Full-Text Search
+
+Powered by Meilisearch for instant, typo-tolerant search results.
+
+- **Keyboard shortcut**: Press `⌘K` or `Ctrl+K` to open search
+- **Typo tolerance**: Finds results even with spelling mistakes
+- **Highlighted results**: See where your query matches
+
+### Search Indexing
+
+Documentation is automatically indexed at build time for fast search.
+
+## Theme & Styling
+
+### Dark Mode
+
+Automatic dark mode that respects system preferences:
+
+- Light mode
+- Dark mode  
+- System preference (auto)
+
+Toggle with the button in the header.
+
+### Customizable Design
+
+All styling is based on CSS variables and Tailwind, making customization easy:
+
+```css
+:root {
+  --primary: oklch(0.55 0.22 264.376);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+}
+```
+
+## Components
+
+### Rich Component Library
+
+Built-in components for common documentation patterns:
+
+<CardGrid cols={3}>
+  <Card icon="message-square" title="Callouts" description="Info, warning, tip, error alerts" />
+  <Card icon="layers" title="Tabs" description="Tabbed content sections" />
+  <Card icon="list" title="Steps" description="Step-by-step guides" />
+  <Card icon="chevrons-up-down" title="Accordion" description="Collapsible content" />
+  <Card icon="grid" title="Cards" description="Feature cards with icons" />
+  <Card icon="code" title="Code Blocks" description="Syntax highlighted code" />
+</CardGrid>
+
+See the [Components](/docs/v1.0.0/components) section for documentation on each component.
+
+## Developer Experience
+
+### Hot Reload
+
+Changes to MDX files are instantly reflected without a full page refresh.
+
+### Frontmatter Validation
+
+Frontmatter fields are validated at build time to catch errors early.
+
+### SEO Optimization
+
+Automatic meta tags, OpenGraph images, and structured data from frontmatter:
+
+- Title and description tags
+- OpenGraph and Twitter cards
+- Canonical URLs
+- Sitemap generation
+
+### Reading Time
+
+Automatic calculation and display of estimated reading time for each page.
+
+## Production Features
+
+### Static Generation
+
+All pages are pre-rendered at build time for maximum performance:
+
+- Zero JavaScript required for content
+- Edge caching friendly
+- Fast Time to First Byte (TTFB)
+
+### Performance
+
+- Lighthouse score: 90+ (desktop)
+- Lazy-loaded images with Next.js Image
+- Code splitting for components
+
+### Accessibility
+
+- Keyboard navigation
+- Screen reader support
+- High contrast support
+- Focus management

package/templates/minimal/docs/v2.0.0/getting-started.mdx

@@ -0,0 +1,183 @@
+---
+title: Getting Started
+description: Set up and start writing documentation with Specra
+sidebar_position: 2
+icon: book
+tab_group: guides
+---
+
+## Prerequisites
+
+Before you begin, make sure you have:
+- Node.js 18+ installed
+- A package manager (npm, yarn, or pnpm)
+
+## Quick Start
+
+<Steps>
+  <Step title="Clone the Repository">
+    ```bash
+    git clone https://github.com/your-org/specra-docs.git
+    cd specra-docs
+    ```
+  </Step>
+  
+  <Step title="Install Dependencies">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+npm install
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+yarn install
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+pnpm install
+```
+      </Tab>
+    </Tabs>
+  </Step>
+  
+  <Step title="Start Development 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>
+
+    Open [http://localhost:3000](http://localhost:3000) to view your docs.
+  </Step>
+</Steps>
+
+## Creating Documentation
+
+<Callout type="warning">
+All documentation files **must use the `.mdx` extension**, not `.md`. MDX enables React components inside your markdown.
+</Callout>
+
+### File Structure
+
+Documentation lives in the `docs/` folder, organized by version:
+
+```txt
+docs/
+├── v1.0.0/               # Version 1.0.0 docs
+│   ├── about.mdx
+│   ├── getting-started.mdx
+│   └── guides/
+│       ├── _category_.json
+│       └── writing-content.mdx
+├── v2.0.0/               # Version 2.0.0 docs
+│   └── ...
+└── next/                 # Unreleased/development docs
+    └── ...
+```
+
+### Creating a New Page
+
+1. Create a new `.mdx` file in the appropriate folder
+2. Add frontmatter at the top of the file
+3. Write your content using Markdown and components
+
+**Example: `docs/v1.0.0/my-page.mdx`**
+
+```mdx
+---
+title: My Page Title
+description: A brief description for SEO
+sidebar_position: 5
+---
+
+# My Page Title
+
+Your content goes here. You can use **Markdown** 
+and <Badge>React components</Badge>.
+```
+
+## Frontmatter
+
+Every MDX file should have frontmatter at the top. Here are the available fields:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | ✅ | Page title (used in sidebar and browser tab) |
+| `description` | Recommended | Short description for SEO meta tags |
+| `sidebar_position` | No | Order in the sidebar (lower = higher) |
+| `tab_group` | No | Tab group name |
+| `tags` | No | Array of tags for categorization |
+| `draft` | No | Set `true` to hide in production |
+| `last_updated` | No | Date string for "last updated" display |
+
+<Callout type="tip">
+Use `sidebar_position` to control the order of pages in the sidebar. Pages are sorted by this number, then alphabetically.
+</Callout>
+
+## Organizing with Folders
+
+Create folders to group related documentation:
+
+```
+docs/v1.0.0/
+├── guides/
+│   ├── _category_.json    # Configure folder display
+│   ├── index.mdx          # Optional: custom folder landing page
+│   ├── installation.mdx
+│   └── configuration.mdx
+```
+
+### Category Configuration
+
+Create `_category_.json` in a folder to customize its sidebar appearance:
+
+```json
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+## Using Components
+
+Specra includes many built-in components. Import is automatic—just use them:
+
+```mdx
+<Callout type="info">
+  This is an info callout!
+</Callout>
+
+<Tabs defaultValue="JavaScript">
+  <Tab label="JavaScript">
+    JavaScript code here
+  </Tab>
+  <Tab label="Python">
+    Python code here
+  </Tab>
+</Tabs>
+```
+
+See the [Components](/docs/v1.0.0/components) section for all available components.
+
+## Next Steps
+
+<CardGrid cols={2}>
+  <Card icon="settings" title="Configuration" description="Customize your docs site" href="/docs/v1.0.0/configuration" />
+  <Card icon="layers" title="Features" description="Explore all platform features" href="/docs/v1.0.0/features" />
+</CardGrid>

package/templates/minimal/gitignore

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

package/templates/minimal/package.json

@@ -0,0 +1,29 @@
+{
+  "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": {
+    "lucide-svelte": "^0.454.0",
+    "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/minimal/postcss.config.mjs

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

package/templates/minimal/specra.config.json

@@ -0,0 +1,91 @@
+{
+  "$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": "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"
+      },
+      {
+        "id": "components",
+        "label": "Components",
+        "icon": "layers"
+      }
+    ]
+  },
+  "social": {
+    "github": "https://github.com/your-org/your-repo"
+  },
+  "search": {
+    "enabled": false
+  },
+  "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"
+          }
+        ]
+      }
+    ],
+    "branding": {
+      "showBranding": true,
+      "logo": "https://specra-docs.com/favicon.svg",
+      "title": "Specra",
+      "url": "https://specra-docs.com"
+    }
+  },
+  "banner": {
+    "enabled": false,
+    "message": "🎉 This is a development version. Some features may not work as expected.",
+    "type": "error",
+    "dismissible": true
+  },
+  "features": {
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true,
+    "i18n": false
+  }
+}

package/templates/minimal/src/app.css

@@ -0,0 +1,86 @@
+@import "specra/styles";
+@source "./**/*.{js,ts,svelte}";
+
+@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/app.html

@@ -0,0 +1,17 @@
+<!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" />
+		<link rel="preconnect" href="https://fonts.googleapis.com">
+		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+		<link
+			href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@100..900&family=Geist:wght@100..900&display=swap"
+			rel="stylesheet">
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover" class="font-sans antialiased">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/templates/minimal/src/hooks.server.ts

@@ -0,0 +1,8 @@
+import { createSecurityHandle } from 'specra/middleware/security';
+import { sequence } from '@sveltejs/kit/hooks';
+
+export const handle = sequence(
+  createSecurityHandle({
+    strictPathValidation: true,
+  })
+);

package/templates/minimal/src/params/product.ts

@@ -0,0 +1,7 @@
+/**
+ * SvelteKit param matcher for product slugs.
+ * Matches any string that does NOT look like a version (e.g., v1.0.0).
+ */
+export function match(param: string): boolean {
+  return !/^v\d/.test(param);
+}

package/templates/minimal/src/routes/+error.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import { page } from '$app/stores';
+  import { VersionNotFound } from 'specra/components';
+</script>
+
+<svelte:head>
+  <title>Page Not Found</title>
+</svelte:head>
+
+<VersionNotFound />

package/templates/minimal/src/routes/+layout.server.ts

@@ -0,0 +1,14 @@
+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 prerender = true;
+export const trailingSlash = 'never';
+
+export const load: LayoutServerLoad = async () => {
+  const config = getConfig();
+  return { config };
+};

package/templates/minimal/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/minimal/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}/about`);
+};