create-specra 0.1.7 → 0.2.0

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.

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

@@ -0,0 +1,112 @@
+---
+title: Testing
+description: Verify your documentation builds and renders correctly
+sidebar_position: 2
+---
+
+This page covers strategies for testing your documentation site to ensure content renders correctly and the build succeeds.
+
+## Build Verification
+
+The simplest test is to run a production build and check for errors:
+
+<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>
+
+The build will fail if:
+- MDX files have syntax errors
+- Frontmatter is malformed
+- Required fields are missing
+
+<Callout type="tip">
+  Run `npm run build` in your CI pipeline to catch documentation errors before they reach production.
+</Callout>
+
+## Type Checking
+
+Verify TypeScript types are correct:
+
+```bash
+npm run check
+```
+
+This catches type errors in your SvelteKit configuration and any custom components.
+
+## Content Checklist
+
+When reviewing documentation changes, verify:
+
+| Check | Description |
+|-------|-------------|
+| **Frontmatter** | All pages have `title`, and key pages have `description` |
+| **Links** | Internal links point to existing pages |
+| **Versions** | Content exists in all active version directories |
+| **Sidebar Order** | `sidebar_position` values create a logical reading flow |
+| **Categories** | Each folder has a `_category_.json` with `label` and `position` |
+
+## Visual Testing
+
+Preview the site locally and check:
+
+<Steps>
+  <Step title="Start Dev Server">
+    Run `npm run dev` and open the site in your browser.
+  </Step>
+
+  <Step title="Check Navigation">
+    Verify sidebar links work, breadcrumbs are correct, and previous/next navigation follows the expected order.
+  </Step>
+
+  <Step title="Check Themes">
+    Toggle between light and dark themes. Ensure all content is readable in both modes.
+  </Step>
+
+  <Step title="Check Responsive">
+    Test on different viewport sizes. The mobile sidebar should collapse into a menu.
+  </Step>
+</Steps>
+
+## Common Issues
+
+### Frontmatter Parsing Errors
+
+```
+Error: Invalid frontmatter in docs/v2.0.0/page.mdx
+```
+
+Ensure your frontmatter uses valid YAML syntax and is enclosed by `---` delimiters.
+
+### Missing Pages
+
+If a page doesn't appear in the sidebar:
+
+1. Check the file has the `.mdx` extension (not `.md`)
+2. Verify the file is in the correct version directory
+3. Check if `draft: true` is set in frontmatter
+
+### Broken Links
+
+If internal links return 404:
+
+1. Check the path matches the file structure
+2. Include the version prefix: `/docs/v2.0.0/page-name`
+3. Use the file's slug (filename without `.mdx`), not the title
+
+<Callout type="info">
+  The dev server shows detailed error messages in the browser overlay. Check the terminal output for build-time errors.
+</Callout>

package/templates/jbrains-docs/gitignore

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

package/templates/jbrains-docs/package.json

@@ -0,0 +1,28 @@
+{
+  "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": {
+    "specra": "^0.2.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^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/jbrains-docs/postcss.config.mjs

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

package/templates/jbrains-docs/public/api-specs/openapi-example.json

@@ -0,0 +1,259 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "User Management API",
+    "version": "1.0.0",
+    "description": "A simple API for managing users (OpenAPI format example)"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com/v1",
+      "description": "Production server"
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "JWT Bearer token authentication"
+      }
+    },
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "example": "user_123"
+          },
+          "name": {
+            "type": "string",
+            "example": "John Doe"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "example": "john@example.com"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "example": "2024-01-15T10:30:00Z"
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string"
+          },
+          "code": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ],
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List all users",
+        "description": "Retrieve a paginated list of all users",
+        "operationId": "listUsers",
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "description": "Page number for pagination",
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "example": 1
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Number of items per page",
+            "schema": {
+              "type": "integer",
+              "default": 10,
+              "example": 10
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of users retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/User"
+                  }
+                },
+                "example": [
+                  {
+                    "id": "user_123",
+                    "name": "John Doe",
+                    "email": "john@example.com",
+                    "createdAt": "2024-01-15T10:30:00Z"
+                  },
+                  {
+                    "id": "user_456",
+                    "name": "Jane Smith",
+                    "email": "jane@example.com",
+                    "createdAt": "2024-01-16T14:20:00Z"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a new user",
+        "description": "Create a new user account",
+        "operationId": "createUser",
+        "requestBody": {
+          "description": "User data to create",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["name", "email"],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "example": "John Doe"
+                  },
+                  "email": {
+                    "type": "string",
+                    "format": "email",
+                    "example": "john@example.com"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "User created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request data",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "example": {
+                  "error": "Email already exists",
+                  "code": "DUPLICATE_EMAIL"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/{id}": {
+      "get": {
+        "summary": "Get user by ID",
+        "description": "Retrieve a single user by their unique identifier",
+        "operationId": "getUserById",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The user's unique identifier",
+            "schema": {
+              "type": "string",
+              "example": "user_123"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "User not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "example": {
+                  "error": "User not found",
+                  "code": "USER_NOT_FOUND"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a user",
+        "description": "Permanently delete a user account",
+        "operationId": "deleteUser",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The user's unique identifier",
+            "schema": {
+              "type": "string",
+              "example": "user_123"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "User deleted successfully"
+          },
+          "404": {
+            "description": "User not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "example": {
+                  "error": "User not found",
+                  "code": "USER_NOT_FOUND"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}