specra-cli 0.3.0

package/templates/jbrains-docs/docs/v2.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/v2.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/v2.0.0/getting-started)
+[Basic Syntax](/docs/v2.0.0/basics/syntax)
+```
+
+### Cross-Version Links
+
+```markdown
+[See v1.0.0 docs](/docs/v1.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/v2.0.0/basics/syntax" />
+  <Card icon="layers" title="Types & Variables" description="Type system and declarations" href="/docs/v2.0.0/basics/types" />
+</CardGrid>

package/templates/jbrains-docs/docs/v2.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/v2.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: '2.0.0',
+  };
+}
+```
+
+```python
+class Document:
+    def __init__(self, title: str):
+        self.title = title
+        self.content = ""
+        self.version = "2.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/v2.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": "2.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/    # Previous version
+├── v2.0.0/    # Current version
+└── next/      # Development version
+```
+
+The active version is set in configuration:
+
+```json
+{
+  "site": {
+    "activeVersion": "v1.0.0"
+  }
+}
+```

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

@@ -0,0 +1,111 @@
+---
+title: Getting Started
+description: Set up your environment and create your first project
+sidebar_position: 2
+icon: rocket
+---
+
+This guide walks you through setting up your development environment and writing your first program.
+
+## Prerequisites
+
+- **Node.js 18+** installed on your machine
+- A code editor (VS Code recommended)
+- A terminal or command line
+
+## Create a Project
+
+<Steps>
+  <Step title="Scaffold the Project">
+    Use the CLI to create a new project:
+
+    ```bash
+    npx create-specra my-project
+    ```
+  </Step>
+
+  <Step title="Install Dependencies">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+cd my-project && npm install
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+cd my-project && yarn install
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+cd my-project && pnpm install
+```
+      </Tab>
+    </Tabs>
+  </Step>
+
+  <Step title="Run the Project">
+    <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:5173` in your browser.
+  </Step>
+</Steps>
+
+## Project Structure
+
+A newly scaffolded project has this structure:
+
+```txt
+my-project/
+├── docs/
+│   ├── v1.0.0/          # Previous version docs
+│   └── v2.0.0/          # Current version docs
+├── src/                  # Application source
+├── specra.config.json    # Configuration
+└── package.json
+```
+
+## Hello World
+
+Create a new file `docs/v2.0.0/hello.mdx`:
+
+```mdx
+---
+title: Hello World
+sidebar_position: 99
+---
+
+# Hello World
+
+This is your first documentation page!
+
+```
+
+<Callout type="tip">
+  Files are automatically picked up by the sidebar. Use `sidebar_position` to control ordering.
+</Callout>
+
+## What's Next
+
+Now that you have a running project, explore the language fundamentals:
+
+<CardGrid cols={2}>
+  <Card icon="code" title="Basic Syntax" description="Learn the fundamental building blocks" href="/docs/v2.0.0/basics/syntax" />
+  <Card icon="layers" title="Types & Variables" description="Understand the type system" href="/docs/v2.0.0/basics/types" />
+</CardGrid>

package/templates/jbrains-docs/docs/v2.0.0/home.mdx

@@ -0,0 +1,37 @@
+---
+title: Home
+description: Welcome to the language documentation
+sidebar_position: 1
+icon: home
+---
+
+Welcome to the v2 documentation. Learn the language from basics to advanced topics, and explore multiplatform tooling.
+
+## Get Started
+
+<CardGrid cols={2}>
+  <Card icon="book-open" title="Get Started" description="Set up your environment and write your first program" href="/docs/v2.0.0/getting-started" />
+  <Card icon="code" title="Basic Syntax" description="Learn the fundamental syntax and structure" href="/docs/v2.0.0/basics/syntax" />
+  <Card icon="layers" title="Types & Variables" description="Understand the type system and variable declarations" href="/docs/v2.0.0/basics/types" />
+  <Card icon="wrench" title="Build Tools" description="Configure and use build tools for your projects" href="/docs/v2.0.0/tools/build-tools" />
+</CardGrid>
+
+## Language
+
+The **Language** section covers everything from basic syntax to advanced features like generics and async programming.
+
+<Callout type="info">
+  If you're new, start with the [Getting Started](/docs/v2.0.0/getting-started) guide, then work through the Basics section.
+</Callout>
+
+## Multiplatform
+
+The **Multiplatform** section covers tooling, build systems, and testing across different platforms and environments.
+
+## What's New in v2
+
+| Feature | Description |
+|---------|-------------|
+| **Improved Build Tools** | Faster builds and better error reporting |
+| **Enhanced Type Checking** | Stricter validation and better diagnostics |
+| **New Components** | Additional built-in components for richer content |

package/templates/jbrains-docs/docs/v2.0.0/tools/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Tools",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "wrench",
+  "tab_group": "multiplatform"
+}

package/templates/jbrains-docs/docs/v2.0.0/tools/build-tools.mdx

@@ -0,0 +1,165 @@
+---
+title: Build Tools
+description: Configure and use build tools for your documentation project
+sidebar_position: 1
+---
+
+This page covers the build tools used to develop, build, and deploy your documentation site.
+
+## Development Server
+
+Start the development server with hot reload:
+
+<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>
+
+The dev server runs on `http://localhost:5173` by default with:
+- **Hot Module Replacement (HMR)** — instant updates when you edit MDX files
+- **Error overlay** — displays build errors in the browser
+- **Fast startup** — powered by Vite
+
+## Production Build
+
+Build the site for production:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run build
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn build
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm build
+```
+  </Tab>
+</Tabs>
+
+This outputs a static site to the `build/` directory.
+
+<Callout type="info">
+  The production build pre-renders all pages for optimal performance and SEO.
+</Callout>
+
+## Preview
+
+Preview the production build locally:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run preview
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn preview
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm preview
+```
+  </Tab>
+</Tabs>
+
+## Vite Configuration
+
+The documentation platform uses Vite as its build tool. The default configuration is in `vite.config.ts`:
+
+```typescript
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [sveltekit()]
+});
+```
+
+## SvelteKit Configuration
+
+SvelteKit is configured in `svelte.config.js`:
+
+```javascript
+import { specraConfig } from 'specra/svelte-config';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+const config = specraConfig({
+  vitePreprocess: { vitePreprocess }
+});
+
+export default config;
+```
+
+## PostCSS & Tailwind
+
+Styling is handled by Tailwind CSS via PostCSS. Configuration is in `postcss.config.mjs`:
+
+```javascript
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;
+```
+
+## TypeScript
+
+TypeScript is configured in `tsconfig.json` with strict mode enabled:
+
+```json
+{
+  "extends": "./.svelte-kit/tsconfig.json",
+  "compilerOptions": {
+    "strict": true,
+    "allowJs": true,
+    "checkJs": true
+  }
+}
+```
+
+## Type Checking
+
+Run the type checker:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run check
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn check
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm check
+```
+  </Tab>
+</Tabs>
+
+This runs `svelte-kit sync` followed by `svelte-check` to verify your TypeScript types.