specra-cli 0.3.0

package/templates/jbrains-docs/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/jbrains-docs/static/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#6366f1"/>
+  <text x="16" y="23" font-family="system-ui,sans-serif" font-size="20" font-weight="bold" fill="white" text-anchor="middle">S</text>
+</svg>

package/templates/jbrains-docs/svelte.config.js

@@ -0,0 +1,13 @@
+import adapter from '@sveltejs/adapter-static';
+import { specraConfig } from 'specra/svelte-config';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+const config = specraConfig({
+  vitePreprocess: { vitePreprocess },
+  kit: {
+    adapter: adapter(),
+    prerender: { handleHttpError: 'warn', handleMissingId: 'warn', handleUnseenRoutes: 'warn' }
+  }
+});
+
+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()]
+});

package/templates/minimal/.env.sample

@@ -0,0 +1 @@
+SPECTRA_TOKEN=sk_xxx...

package/templates/minimal/docs/v1.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/v1.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/v1.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/v1.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/v1.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/v1.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 |