specra-cli 0.3.0

package/templates/book-docs/docs/v1.0.0/introduction.mdx

@@ -0,0 +1,38 @@
+---
+title: Introduction
+description: Welcome to the documentation
+sidebar_position: 1
+icon: book
+---
+
+Welcome to the documentation. This knowledge base covers everything you need to get started, create content, and customize your site.
+
+## Quick Links
+
+<CardGrid cols={2}>
+  <Card icon="zap" title="Quick Start" description="Get up and running in under 5 minutes" href="/docs/v1.0.0/quickstart" />
+  <Card icon="book-open" title="Core Concepts" description="Understand the key ideas behind the platform" href="/docs/v1.0.0/concepts" />
+  <Card icon="file-text" title="Content Guide" description="Learn how to write and organize content" href="/docs/v1.0.0/content/formatting" />
+  <Card icon="palette" title="Customization" description="Themes, branding, and design options" href="/docs/v1.0.0/customization/themes" />
+</CardGrid>
+
+## Overview
+
+This documentation platform gives you a modern, fast, and beautiful docs experience out of the box. It supports:
+
+- **Versioned documentation** — maintain docs for multiple releases
+- **Dark and light themes** — automatic or manual switching
+- **Rich components** — callouts, tabs, code blocks, cards, and more
+- **Sidebar navigation** — auto-generated from your file structure
+- **Full-text search** — find anything instantly
+
+<Callout type="tip">
+  Use the sidebar to navigate between sections, or use the search bar to find specific topics.
+</Callout>
+
+## What's New
+
+| Version | Highlights |
+|---------|------------|
+| **v2.0.0** | New customization options, improved performance |
+| **v1.0.0** | Initial release with core features |

package/templates/book-docs/docs/v1.0.0/quickstart.mdx

@@ -0,0 +1,112 @@
+---
+title: Quick Start
+description: Get up and running in under 5 minutes
+sidebar_position: 2
+icon: zap
+---
+
+Follow these steps to set up your documentation site and start writing content.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Node.js 18+** installed
+- A package manager (**npm**, **yarn**, or **pnpm**)
+
+## Installation
+
+<Steps>
+  <Step title="Create a New Project">
+    Run the CLI to scaffold a new documentation site:
+
+    ```bash
+    npx create-specra my-docs
+    ```
+  </Step>
+
+  <Step title="Install Dependencies">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+cd my-docs && npm install
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+cd my-docs && yarn install
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+cd my-docs && pnpm install
+```
+      </Tab>
+    </Tabs>
+  </Step>
+
+  <Step title="Start the Dev 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>
+
+    Your docs site is now running at `http://localhost:5173`.
+  </Step>
+</Steps>
+
+## Project Structure
+
+After scaffolding, your project looks like this:
+
+```txt
+my-docs/
+├── docs/
+│   ├── v1.0.0/          # Your documentation files
+│   └── v2.0.0/          # Another version
+├── src/                  # SvelteKit application
+├── specra.config.json    # Site configuration
+└── package.json
+```
+
+<Callout type="info">
+  All documentation lives in the `docs/` directory as `.mdx` files. The sidebar is automatically generated from the folder structure.
+</Callout>
+
+## Creating Your First Page
+
+Create a new file at `docs/v1.0.0/my-page.mdx`:
+
+```mdx
+---
+title: My First Page
+description: A page I just created
+sidebar_position: 10
+---
+
+# Hello World
+
+This is my first documentation page.
+```
+
+Save the file and it will appear in the sidebar automatically.
+
+## Next Steps
+
+<CardGrid cols={2}>
+  <Card icon="lightbulb" title="Core Concepts" description="Learn the key ideas" href="/docs/v1.0.0/concepts" />
+  <Card icon="file-text" title="Formatting" description="Style your content" href="/docs/v1.0.0/content/formatting" />
+</CardGrid>

package/templates/book-docs/docs/v2.0.0/concepts.mdx

@@ -0,0 +1,89 @@
+---
+title: Core Concepts
+description: Understand the key ideas behind the documentation platform
+sidebar_position: 3
+icon: lightbulb
+---
+
+Before diving into content creation, it helps to understand a few core concepts that shape how the platform works.
+
+## MDX
+
+MDX is Markdown with components. You write standard Markdown and can embed rich, interactive components directly in your content.
+
+```mdx
+# Regular Markdown
+
+This is a paragraph with **bold** and *italic* text.
+
+<Callout type="tip">
+  And this is an interactive component inside Markdown!
+</Callout>
+```
+
+<Callout type="info">
+  All documentation files use the `.mdx` extension, not `.md`.
+</Callout>
+
+## Frontmatter
+
+Every page starts with frontmatter — a YAML block at the top of the file that defines metadata:
+
+```mdx
+---
+title: Page Title
+description: A short description for SEO
+sidebar_position: 1
+icon: book
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Page title shown in sidebar and browser tab |
+| `description` | Recommended | Short description for search engines |
+| `sidebar_position` | No | Controls order in sidebar (lower number = higher up) |
+| `icon` | No | Lucide icon name for the sidebar |
+| `tags` | No | Array of tags for categorization |
+
+## Versioning
+
+Documentation is organized by version. Each version lives in its own folder:
+
+```txt
+docs/
+├── v1.0.0/    # Previous release
+├── v2.0.0/    # Current release
+└── next/      # Development docs
+```
+
+Users can switch between versions using the version selector in the header.
+
+## Sidebar Navigation
+
+The sidebar is automatically generated from your folder structure. You control the order and appearance using:
+
+- **`sidebar_position`** in frontmatter — sets page order
+- **`_category_.json`** in folders — configures section labels and behavior
+
+```json
+{
+  "label": "Getting Started",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+## Components
+
+The platform includes a library of built-in components that you can use without any imports:
+
+<CardGrid cols={3}>
+  <Card icon="message-square" title="Callouts" description="Highlight important info" />
+  <Card icon="layers" title="Tabs" description="Tabbed content panels" />
+  <Card icon="list" title="Steps" description="Step-by-step guides" />
+  <Card icon="grid" title="Cards" description="Feature cards with icons" />
+  <Card icon="code" title="Code Blocks" description="Syntax-highlighted code" />
+  <Card icon="chevrons-up-down" title="Accordion" description="Collapsible sections" />
+</CardGrid>

package/templates/book-docs/docs/v2.0.0/content/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Content",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "file-text"
+}

package/templates/book-docs/docs/v2.0.0/content/formatting.mdx

@@ -0,0 +1,128 @@
+---
+title: Formatting
+description: Format your content with Markdown and components
+sidebar_position: 1
+---
+
+This guide covers the formatting options available for your documentation pages.
+
+## Text Formatting
+
+Standard Markdown formatting is fully supported:
+
+| Syntax | Output |
+|--------|--------|
+| `**bold**` | **bold** |
+| `*italic*` | *italic* |
+| `` `code` `` | `code` |
+| `~~strikethrough~~` | ~~strikethrough~~ |
+
+## Headings
+
+Use headings to structure your content. The table of contents on the right is generated from your headings.
+
+```markdown
+## Second Level
+### Third Level
+#### Fourth Level
+```
+
+<Callout type="tip">
+  Start with `##` (H2) in your content. The page title from frontmatter is rendered as H1 automatically.
+</Callout>
+
+## Lists
+
+### Unordered Lists
+
+```markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+```
+
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+
+### Ordered Lists
+
+1. First step
+2. Second step
+3. Third step
+
+## Code Blocks
+
+Use fenced code blocks with a language identifier for syntax highlighting:
+
+```typescript
+interface Config {
+  title: string;
+  theme: 'light' | 'dark' | 'system';
+  version: string;
+}
+
+function loadConfig(path: string): Config {
+  const raw = readFileSync(path, 'utf-8');
+  return JSON.parse(raw);
+}
+```
+
+## Tables
+
+```markdown
+| Feature | Status |
+|---------|--------|
+| Dark Mode | Supported |
+| Search | Supported |
+| i18n | Coming Soon |
+```
+
+| Feature | Status |
+|---------|--------|
+| Dark Mode | Supported |
+| Search | Supported |
+| i18n | Coming Soon |
+
+## Callouts
+
+Use callouts to draw attention to important information:
+
+<Callout type="info">
+  Informational callouts provide additional context.
+</Callout>
+
+<Callout type="warning">
+  Warning callouts alert readers to potential issues.
+</Callout>
+
+<Callout type="tip">
+  Tip callouts suggest best practices or shortcuts.
+</Callout>
+
+## Tabs
+
+Use tabs to show alternative content side by side:
+
+<Tabs defaultValue="JavaScript">
+  <Tab label="JavaScript">
+```javascript
+console.log("Hello, world!");
+```
+  </Tab>
+  <Tab label="Python">
+```python
+print("Hello, world!")
+```
+  </Tab>
+</Tabs>
+
+## Links
+
+- **Internal links**: `[Getting Started](/docs/v2.0.0/quickstart)`
+- **External links**: `[GitHub](https://github.com)`
+- **Anchor links**: `[See below](#callouts)`

package/templates/book-docs/docs/v2.0.0/content/reusable-content.mdx

@@ -0,0 +1,116 @@
+---
+title: Reusable Content
+description: Create reusable content blocks for consistent documentation
+sidebar_position: 3
+---
+
+Reusable content helps you maintain consistency across your documentation by defining content once and using it in multiple places.
+
+## Components as Reusable Blocks
+
+The built-in component library provides reusable patterns for common documentation needs.
+
+### Card Grids
+
+Use card grids to create consistent navigation sections across pages:
+
+<CardGrid cols={3}>
+  <Card icon="zap" title="Fast" description="Optimized for speed" />
+  <Card icon="shield" title="Secure" description="Built with security in mind" />
+  <Card icon="code" title="Developer First" description="Great developer experience" />
+</CardGrid>
+
+### Step-by-Step Patterns
+
+Use the Steps component for consistent instructional content:
+
+<Steps>
+  <Step title="Define the Content">
+    Write your content in MDX format with clear, concise language.
+  </Step>
+
+  <Step title="Add Components">
+    Enhance your content with interactive components like callouts, tabs, and cards.
+  </Step>
+
+  <Step title="Review and Publish">
+    Preview your changes locally, then commit and deploy.
+  </Step>
+</Steps>
+
+## Consistent Callout Patterns
+
+Use standardized callout types across your docs for a consistent reading experience:
+
+<Callout type="info">
+  **Info callouts** provide supplementary context that helps readers understand a topic better.
+</Callout>
+
+<Callout type="warning">
+  **Warning callouts** alert readers about potential pitfalls or breaking changes.
+</Callout>
+
+<Callout type="tip">
+  **Tip callouts** share best practices and shortcuts that improve the reader's workflow.
+</Callout>
+
+## Tabbed Content Patterns
+
+Use tabs to provide content variations. Common patterns include:
+
+### Installation Instructions
+
+<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>
+
+### Language Examples
+
+<Tabs defaultValue="TypeScript">
+  <Tab label="TypeScript">
+```typescript
+const greeting: string = "Hello, world!";
+console.log(greeting);
+```
+  </Tab>
+  <Tab label="Python">
+```python
+greeting = "Hello, world!"
+print(greeting)
+```
+  </Tab>
+  <Tab label="Go">
+```go
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Println("Hello, world!")
+}
+```
+  </Tab>
+</Tabs>
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Use consistent types** | Always use the same callout type for the same kind of information |
+| **Keep cards brief** | Card descriptions should be one short sentence |
+| **Limit tab count** | Use 2-4 tabs per group for readability |
+| **Name tabs clearly** | Tab labels should be short and descriptive |

package/templates/book-docs/docs/v2.0.0/content/structure.mdx

@@ -0,0 +1,92 @@
+---
+title: Content Structure
+description: Organize your documentation with folders and categories
+sidebar_position: 2
+---
+
+Learn how to organize your documentation into a clear, navigable structure.
+
+## File Organization
+
+Documentation files live in the `docs/` directory, grouped by version:
+
+```txt
+docs/
+├── v1.0.0/
+│   ├── introduction.mdx
+│   ├── quickstart.mdx
+│   ├── guides/
+│   │   ├── _category_.json
+│   │   ├── installation.mdx
+│   │   └── deployment.mdx
+│   └── reference/
+│       ├── _category_.json
+│       └── api.mdx
+└── v2.0.0/
+    └── ...
+```
+
+## Categories
+
+Folders become sidebar sections. Add a `_category_.json` file to configure each section:
+
+```json
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "book-open"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `label` | Display name in the sidebar |
+| `position` | Order relative to other sections |
+| `collapsible` | Whether the section can be collapsed |
+| `collapsed` | Whether the section starts collapsed |
+| `icon` | Lucide icon name |
+
+## Page Ordering
+
+Pages within a section are ordered by their `sidebar_position` frontmatter value:
+
+```mdx
+---
+title: First Page
+sidebar_position: 1
+---
+```
+
+<Callout type="info">
+  Pages without a `sidebar_position` are sorted alphabetically after positioned pages.
+</Callout>
+
+## Index Pages
+
+Create an `index.mdx` in a folder to provide a landing page for that section. When users click the section header in the sidebar, they'll see this page.
+
+```txt
+guides/
+├── _category_.json
+├── index.mdx          # Landing page for "Guides"
+├── installation.mdx
+└── deployment.mdx
+```
+
+## Best Practices
+
+<Steps>
+  <Step title="Keep It Flat">
+    Avoid deeply nested folders. Two levels of nesting is usually enough for most documentation sites.
+  </Step>
+
+  <Step title="Use Descriptive Names">
+    File names become URL slugs. Use lowercase, hyphenated names like `getting-started.mdx`.
+  </Step>
+
+  <Step title="Group Related Content">
+    Put related pages in the same folder. This makes the sidebar intuitive and keeps URLs predictable.
+  </Step>
+</Steps>

package/templates/book-docs/docs/v2.0.0/customization/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Customization",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "palette"
+}

package/templates/book-docs/docs/v2.0.0/customization/branding.mdx

@@ -0,0 +1,115 @@
+---
+title: Branding
+description: Customize logos, site title, and brand identity
+sidebar_position: 2
+---
+
+Make the documentation site match your brand by customizing the title, description, social links, and footer.
+
+## Site Identity
+
+Configure basic site information in `specra.config.json`:
+
+```json
+{
+  "site": {
+    "title": "My Project Docs",
+    "description": "Official documentation for My Project",
+    "url": "https://docs.myproject.com",
+    "organizationName": "My Organization",
+    "projectName": "my-project"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `title` | Displayed in the header and browser tab |
+| `description` | Used for SEO meta tags |
+| `url` | Full URL where docs are hosted |
+| `organizationName` | Your company or organization name |
+| `projectName` | Project identifier |
+
+## Social Links
+
+Add links to your social profiles and repositories:
+
+```json
+{
+  "social": {
+    "github": "https://github.com/your-org/your-repo",
+    "twitter": "https://twitter.com/yourhandle",
+    "discord": "https://discord.gg/yourserver"
+  }
+}
+```
+
+Social links appear as icons in the site header.
+
+## Footer
+
+Customize the footer with copyright text and link columns:
+
+```json
+{
+  "footer": {
+    "copyright": "Copyright © 2025 My Organization. All rights reserved.",
+    "branding": {
+      "showBranding": true
+    },
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          { "label": "Getting Started", "href": "/docs/v2.0.0/quickstart" },
+          { "label": "Concepts", "href": "/docs/v2.0.0/concepts" }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          { "label": "GitHub", "href": "https://github.com/your-org" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+<Callout type="info">
+  The footer supports multiple link columns. Each column has a title and a list of labeled links.
+</Callout>
+
+## Banner
+
+Display a site-wide announcement banner:
+
+```json
+{
+  "banner": {
+    "enabled": true,
+    "message": "We just launched v2.0 — check out what's new!",
+    "type": "info",
+    "dismissible": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Show or hide the banner |
+| `message` | `string` | Banner text content |
+| `type` | `"info" \| "warning" \| "error"` | Visual style |
+| `dismissible` | `boolean` | Allow users to close the banner |
+
+## Favicon
+
+Place your favicon file in the `public/` directory and reference it in `src/app.html`:
+
+```html
+<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+```
+
+<Callout type="tip">
+  Use SVG favicons for crisp rendering at any size and automatic dark mode support.
+</Callout>