specra-cli 0.3.0

package/templates/book-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/jbrains-docs/.env.sample

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

package/templates/jbrains-docs/docs/v1.0.0/advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Advanced",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "graduation-cap",
+  "tab_group": "language"
+}

package/templates/jbrains-docs/docs/v1.0.0/advanced/async.mdx

@@ -0,0 +1,95 @@
+---
+title: Async Programming
+description: Asynchronous data loading and dynamic content
+sidebar_position: 2
+---
+
+This page covers how the documentation platform handles asynchronous operations like data loading, content processing, and dynamic rendering.
+
+## How Content Loading Works
+
+Documentation pages are loaded asynchronously at build time and on navigation. The platform uses SvelteKit's server-side loading to fetch and process MDX content:
+
+```typescript
+export const load: PageServerLoad = async ({ params }) => {
+  const { version, slug } = params;
+  const doc = await getCachedDocBySlug(slug, version);
+  const allDocs = await getCachedAllDocs(version);
+  return { doc, allDocs, version, slug };
+};
+```
+
+<Callout type="info">
+  Content is cached after the first load, so subsequent navigations are nearly instant.
+</Callout>
+
+## Server-Side Data Flow
+
+The data loading follows this pipeline:
+
+<Steps>
+  <Step title="Route Matching">
+    SvelteKit matches the URL to a route pattern like `/docs/[version]/[...slug]`.
+  </Step>
+
+  <Step title="Data Loading">
+    The `+page.server.ts` load function runs, fetching the document and sidebar data.
+  </Step>
+
+  <Step title="MDX Processing">
+    The MDX content is parsed, components are resolved, and the content tree is built.
+  </Step>
+
+  <Step title="Rendering">
+    The Svelte component renders the processed content with all interactive components.
+  </Step>
+</Steps>
+
+## Configuration Loading
+
+Configuration is loaded once at application startup and cached:
+
+```typescript
+import { initConfig, getConfig } from 'specra';
+import specraConfig from '../../specra.config.json';
+
+initConfig(specraConfig);
+
+const config = getConfig(); // Cached after first call
+```
+
+## Version Resolution
+
+When a user navigates to the root URL, the system resolves the active version and redirects:
+
+```typescript
+export const load: PageServerLoad = async () => {
+  const config = getConfig();
+  const activeVersion = config.site?.activeVersion || 'v1.0.0';
+  redirect(302, `/docs/${activeVersion}/home`);
+};
+```
+
+## Adjacent Document Resolution
+
+Previous and next links are computed asynchronously from the full document list:
+
+```typescript
+const { previous, next } = getAdjacentDocs(slug, allDocs);
+```
+
+This enables linear navigation through the documentation in sidebar order.
+
+## Table of Contents Extraction
+
+The table of contents is extracted from heading elements in the content:
+
+```typescript
+const toc = extractTableOfContents(doc.content);
+```
+
+This returns a structured list of headings with their depths and anchor IDs.
+
+<Callout type="tip">
+  All these async operations are handled by the platform automatically. You only need to write MDX content — the data loading pipeline is built in.
+</Callout>

package/templates/jbrains-docs/docs/v1.0.0/advanced/generics.mdx

@@ -0,0 +1,126 @@
+---
+title: Generics
+description: Create reusable, type-safe documentation patterns
+sidebar_position: 1
+---
+
+Generics in the context of this documentation platform refer to creating reusable, parameterized content patterns that work across different contexts.
+
+## Reusable Component Patterns
+
+The built-in component library provides generic patterns that adapt to your content:
+
+### Cards
+
+Cards accept different props to serve different purposes:
+
+<CardGrid cols={3}>
+  <Card icon="zap" title="Feature Card" description="Showcase a feature" />
+  <Card icon="book" title="Guide Card" description="Link to a guide" href="/docs/v1.0.0/getting-started" />
+  <Card icon="code" title="Code Card" description="Reference a code concept" />
+</CardGrid>
+
+### Tabs
+
+Tabs provide generic containers for alternative content:
+
+<Tabs defaultValue="Pattern A">
+  <Tab label="Pattern A">
+    Use tabs for installation instructions across different package managers.
+
+    ```bash
+    npm install my-package
+    ```
+  </Tab>
+  <Tab label="Pattern B">
+    Use tabs for code examples across different languages.
+
+    ```python
+    pip install my-package
+    ```
+  </Tab>
+  <Tab label="Pattern C">
+    Use tabs for platform-specific instructions.
+
+    ```bash
+    brew install my-package
+    ```
+  </Tab>
+</Tabs>
+
+## Generic Page Templates
+
+### Landing Pages
+
+Landing pages use CardGrid to create navigation hubs:
+
+```mdx
+---
+title: Section Landing
+---
+
+<CardGrid cols={2}>
+  <Card title="Topic A" description="Description" href="/path" />
+  <Card title="Topic B" description="Description" href="/path" />
+</CardGrid>
+```
+
+### Reference Pages
+
+Reference pages use tables and code blocks:
+
+```mdx
+---
+title: API Reference
+---
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The item name |
+| `value` | `number` | The item value |
+```
+
+### Tutorial Pages
+
+Tutorial pages use Steps for structured guidance:
+
+```mdx
+---
+title: Tutorial
+---
+
+<Steps>
+  <Step title="Step 1">Instructions here</Step>
+  <Step title="Step 2">More instructions</Step>
+</Steps>
+```
+
+## Callout Types as Generic Patterns
+
+Each callout type serves a specific semantic purpose:
+
+<Callout type="info">
+  **Info** — Supplementary context that enriches understanding.
+</Callout>
+
+<Callout type="tip">
+  **Tip** — Practical advice that improves the reader's workflow.
+</Callout>
+
+<Callout type="warning">
+  **Warning** — Important caveats or potential issues to be aware of.
+</Callout>
+
+<Callout type="error">
+  **Error** — Critical mistakes to avoid or known issues.
+</Callout>
+
+## Best Practices
+
+| Pattern | When to Use |
+|---------|-------------|
+| CardGrid | Hub pages, feature showcases, navigation |
+| Tabs | Alternative content (languages, platforms, package managers) |
+| Steps | Sequential instructions, tutorials |
+| Callouts | Inline annotations (tips, warnings, notes) |
+| Tables | Reference data, comparisons, specifications |

package/templates/jbrains-docs/docs/v1.0.0/basics/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Basics",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "book",
+  "tab_group": "language"
+}

package/templates/jbrains-docs/docs/v1.0.0/basics/control-flow.mdx

@@ -0,0 +1,106 @@
+---
+title: Control Flow
+description: Navigation flow and content organization
+sidebar_position: 3
+---
+
+This page explains how navigation flow works in the documentation system — how users move between pages and how you control the reading path.
+
+## Sidebar Navigation
+
+The sidebar is the primary navigation mechanism. It is automatically generated from the file and folder structure in `docs/`:
+
+```txt
+docs/v1.0.0/
+├── home.mdx                  → Top-level page
+├── getting-started.mdx       → Top-level page
+├── basics/
+│   ├── _category_.json       → Section configuration
+│   ├── syntax.mdx            → Page in section
+│   ├── types.mdx             → Page in section
+│   └── control-flow.mdx      → Page in section
+```
+
+Pages are sorted by `sidebar_position`, then alphabetically.
+
+## Previous/Next Navigation
+
+At the bottom of each page, previous and next links are automatically generated based on the sidebar order. This creates a linear reading path through the documentation.
+
+<Callout type="tip">
+  Design your `sidebar_position` values to create a logical reading flow from introduction to advanced topics.
+</Callout>
+
+## Tab Groups
+
+Tab groups split the sidebar into separate tabbed sections. This is useful when documentation covers distinct but related areas:
+
+```json
+{
+  "navigation": {
+    "tabGroups": [
+      { "id": "language", "label": "Language" },
+      { "id": "multiplatform", "label": "Multiplatform" }
+    ]
+  }
+}
+```
+
+Assign categories to tab groups in `_category_.json`:
+
+```json
+{
+  "label": "Basics",
+  "tab_group": "language"
+}
+```
+
+<Callout type="info">
+  Pages not assigned to any tab group appear in all tabs. Use tab groups to separate conceptually different areas of documentation.
+</Callout>
+
+## Breadcrumbs
+
+Breadcrumbs show the user's current position in the documentation hierarchy:
+
+```
+Home > Basics > Control Flow
+```
+
+Enable or disable breadcrumbs in configuration:
+
+```json
+{
+  "navigation": {
+    "showBreadcrumbs": true
+  }
+}
+```
+
+## Version Switching
+
+Users can switch between documentation versions using the version selector in the header. The system attempts to navigate to the same page in the selected version.
+
+## Linking Between Pages
+
+Use standard Markdown links with the full path:
+
+```markdown
+[Getting Started](/docs/v1.0.0/getting-started)
+[Basic Syntax](/docs/v1.0.0/basics/syntax)
+```
+
+### Cross-Version Links
+
+```markdown
+[See v2.0.0 docs](/docs/v2.0.0/getting-started)
+```
+
+## Cards as Navigation
+
+Use CardGrid for hub pages that direct users to different sections:
+
+<CardGrid cols={2}>
+  <Card icon="code" title="Basic Syntax" description="The fundamental building blocks" href="/docs/v1.0.0/basics/syntax" />
+  <Card icon="layers" title="Types & Variables" description="Type system and declarations" href="/docs/v1.0.0/basics/types" />
+</CardGrid>

package/templates/jbrains-docs/docs/v1.0.0/basics/syntax.mdx

@@ -0,0 +1,129 @@
+---
+title: Basic Syntax
+description: Learn the fundamental syntax and structure
+sidebar_position: 1
+---
+
+This page covers the essential syntax you need to know to start writing documentation content with MDX.
+
+## Page Structure
+
+Every MDX page starts with frontmatter followed by content:
+
+```mdx
+---
+title: Page Title
+description: Page description
+sidebar_position: 1
+---
+
+Your content goes here.
+```
+
+The frontmatter is a YAML block enclosed by `---` lines. It defines metadata about the page.
+
+## Markdown Basics
+
+MDX supports all standard Markdown syntax:
+
+### Text Formatting
+
+```markdown
+**Bold text**
+*Italic text*
+`Inline code`
+~~Strikethrough~~
+```
+
+**Bold text**, *Italic text*, `Inline code`, ~~Strikethrough~~
+
+### Links
+
+```markdown
+[Internal link](/docs/v1.0.0/getting-started)
+[External link](https://example.com)
+```
+
+### Images
+
+```markdown
+![Alt text](/path/to/image.png)
+```
+
+## Code Blocks
+
+Fenced code blocks support syntax highlighting for many languages:
+
+```typescript
+interface Document {
+  title: string;
+  content: string;
+  version: string;
+}
+
+function createDocument(title: string): Document {
+  return {
+    title,
+    content: '',
+    version: '1.0.0',
+  };
+}
+```
+
+```python
+class Document:
+    def __init__(self, title: str):
+        self.title = title
+        self.content = ""
+        self.version = "1.0.0"
+```
+
+## Components in MDX
+
+MDX lets you use components directly in your Markdown. Components are available globally — no imports needed:
+
+```mdx
+<Callout type="info">
+  This is a callout component inside MDX.
+</Callout>
+```
+
+<Callout type="info">
+  This is a callout component inside MDX.
+</Callout>
+
+## Headings
+
+Use headings to create document structure. The table of contents (when enabled) is generated from H2 and H3 headings:
+
+```markdown
+## Section (H2)
+### Subsection (H3)
+#### Detail (H4)
+```
+
+<Callout type="tip">
+  Start your content with H2 (`##`). The page title from frontmatter automatically renders as H1.
+</Callout>
+
+## Lists
+
+### Unordered
+
+- First item
+- Second item
+  - Nested item
+- Third item
+
+### Ordered
+
+1. First step
+2. Second step
+3. Third step
+
+## Tables
+
+| Column A | Column B | Column C |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |

package/templates/jbrains-docs/docs/v1.0.0/basics/types.mdx

@@ -0,0 +1,135 @@
+---
+title: Types & Variables
+description: Understand the type system and variable declarations
+sidebar_position: 2
+---
+
+This page covers how content types and configuration variables work in the documentation platform.
+
+## Frontmatter Types
+
+Frontmatter fields have specific types that the system validates:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | `string` | Yes | Page title |
+| `description` | `string` | No | SEO description |
+| `sidebar_position` | `number` | No | Sidebar ordering |
+| `icon` | `string` | No | Lucide icon name |
+| `tab_group` | `string` | No | Tab group assignment |
+| `tags` | `string[]` | No | Content tags |
+| `draft` | `boolean` | No | Hide in production |
+
+## Configuration Types
+
+The `specra.config.json` file uses typed configuration:
+
+### Theme Configuration
+
+```typescript
+interface ThemeConfig {
+  defaultMode: 'light' | 'dark' | 'system';
+  respectPrefersColorScheme: boolean;
+}
+```
+
+Example:
+
+```json
+{
+  "theme": {
+    "defaultMode": "light",
+    "respectPrefersColorScheme": true
+  }
+}
+```
+
+### Navigation Configuration
+
+```typescript
+interface NavigationConfig {
+  showSidebar: boolean;
+  collapsibleSidebar: boolean;
+  showBreadcrumbs: boolean;
+  showTableOfContents: boolean;
+  tocPosition: 'left' | 'right';
+  tocMaxDepth: number;
+  tabGroups?: TabGroup[];
+}
+
+interface TabGroup {
+  id: string;
+  label: string;
+  icon?: string;
+}
+```
+
+<Callout type="info">
+  Tab groups allow you to split sidebar content into separate sections. Each category folder can be assigned to a tab group using `tab_group` in its `_category_.json`.
+</Callout>
+
+### Category Configuration
+
+Categories are defined with `_category_.json` files:
+
+```typescript
+interface CategoryConfig {
+  label: string;
+  position: number;
+  collapsible: boolean;
+  collapsed: boolean;
+  icon?: string;
+  tab_group?: string;
+}
+```
+
+Example:
+
+```json
+{
+  "label": "Basics",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "book",
+  "tab_group": "language"
+}
+```
+
+## Content Variables
+
+Environment variables can be defined in configuration and used in content:
+
+```json
+{
+  "env": {
+    "API_URL": "https://api.example.com",
+    "VERSION": "1.0.0"
+  }
+}
+```
+
+<Callout type="tip">
+  Use environment variables for values that change between environments, like API URLs or version numbers.
+</Callout>
+
+## Version Variables
+
+The documentation supports multiple versions. Each version is a folder under `docs/`:
+
+```txt
+docs/
+├── v1.0.0/    # Version 1.0.0
+├── v2.0.0/    # Version 2.0.0
+└── next/      # Development version
+```
+
+The active version is set in configuration:
+
+```json
+{
+  "site": {
+    "activeVersion": "v1.0.0"
+  }
+}
+```