create-specra 0.1.0

package/templates/minimal/docs/v1.0.0/configuration.mdx

@@ -0,0 +1,322 @@
+---
+title: Configuration
+description: Configure your Specra documentation site with specra.config.json
+sidebar_position: 3
+icon: cog
+tab_group: guides
+---
+
+Specra uses a centralized configuration file `specra.config.json` at the project root to manage all settings.
+
+## Complete Configuration Example
+
+Here's a complete example showing all available configuration options:
+
+```json
+{
+  "$schema": "./lib/config.types.ts",
+  "site": {
+    "title": "Documentation Library",
+    "description": "Comprehensive documentation for your project",
+    "url": "https://your-docs.com",
+    "baseUrl": "/",
+    "language": "en",
+    "organizationName": "Your Organization",
+    "projectName": "your-project",
+    "activeVersion": "v1.0.0",
+    "favicon": "/icon-light-32x32.png"
+  },
+  "theme": {
+    "defaultMode": "system",
+    "respectPrefersColorScheme": true
+  },
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "tocPosition": "right",
+    "tocMaxDepth": 3,
+    "tabGroups": [
+      {
+        "id": "guides",
+        "label": "Guides",
+        "icon": "book-open"
+      },
+      {
+        "id": "api",
+        "label": "API Reference",
+        "icon": "zap"
+      }
+    ]
+  },
+  "social": {
+    "github": "https://github.com/your-org/your-repo",
+    "twitter": "https://twitter.com/your-handle",
+    "discord": "https://discord.gg/your-server",
+    "custom": [
+      {
+        "label": "Website",
+        "href": "https://yourwebsite.com"
+      }
+    ]
+  },
+  "search": {
+    "enabled": true,
+    "placeholder": "Search documentation...",
+    "provider": "meilisearch",
+    "meilisearch": {
+      "host": "http://localhost:7700",
+      "apiKey": "your-api-key",
+      "indexName": "docs"
+    }
+  },
+  "analytics": {
+    "googleAnalytics": "G-XXXXXXXXXX",
+    "plausible": "your-domain.com"
+  },
+  "footer": {
+    "copyright": "Copyright © 2024 Your Organization. All rights reserved.",
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          {
+            "label": "Getting Started",
+            "href": "/docs/v1.0.0/getting-started"
+          },
+          {
+            "label": "API Reference",
+            "href": "/docs/v1.0.0/api-overview"
+          }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          {
+            "label": "GitHub",
+            "href": "https://github.com/your-org/your-repo"
+          },
+          {
+            "label": "Discord",
+            "href": "https://discord.gg/your-server"
+          }
+        ]
+      }
+    ]
+  },
+  "banner": {
+    "enabled": true,
+    "message": "�� Version 2.0 is now available!",
+    "type": "info",
+    "dismissible": true
+  },
+  "features": {
+    "editUrl": "https://github.com/your-org/your-repo/edit/main/docs",
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true,
+    "i18n": false
+  },
+  "env": {
+    "API_BASE_URL": "https://api.example.com",
+    "API_VERSION": "v1",
+    "CDN_URL": "https://cdn.example.com"
+  },
+  "deployment": {
+    "target": "vercel",
+    "basePath": "",
+    "customDomain": false
+  }
+}
+```
+
+<Callout type="tip">
+Copy this complete configuration as a starting point and customize it for your needs.
+</Callout>
+
+## Site Configuration
+
+Core metadata and branding for your documentation site.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title` | string | Site title (shown in header and browser tab) |
+| `description` | string | Meta description for SEO |
+| `url` | string | Full URL where docs are hosted |
+| `baseUrl` | string | Base path (default: `/`) |
+| `language` | string | Language code (default: `en`) |
+| `activeVersion` | string | Default documentation version |
+| `organizationName` | string | Your organization name |
+| `projectName` | string | Project name |
+
+## Theme Configuration
+
+Control the appearance and color scheme.
+
+```json
+{
+  "theme": {
+    "defaultMode": "system",
+    "respectPrefersColorScheme": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `defaultMode` | `"light" \| "dark" \| "system"` | Default theme mode |
+| `respectPrefersColorScheme` | boolean | Follow system theme preference |
+
+## Navigation Configuration
+
+Control sidebar, breadcrumbs, and table of contents.
+
+```json
+{
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "tocPosition": "right",
+    "tocMaxDepth": 3
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `showSidebar` | boolean | Show/hide the sidebar |
+| `collapsibleSidebar` | boolean | Allow sections to collapse |
+| `showBreadcrumbs` | boolean | Show breadcrumb navigation |
+| `showTableOfContents` | boolean | Show table of contents |
+| `tocPosition` | `"left" \| "right"` | TOC position |
+| `tocMaxDepth` | number | Maximum heading depth for TOC (1-6) |
+
+## Search Configuration
+
+Configure the search functionality.
+
+```json
+{
+  "search": {
+    "enabled": true,
+    "placeholder": "Search documentation...",
+    "provider": "meilisearch",
+    "meilisearch": {
+      "host": "http://localhost:7700",
+      "apiKey": "your-api-key",
+      "indexName": "docs"
+    }
+  }
+}
+```
+
+<Callout type="info">
+Press **⌘K** (Mac) or **Ctrl+K** (Windows/Linux) to open the search modal.
+</Callout>
+
+## 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"
+  }
+}
+```
+
+## Features Configuration
+
+Toggle documentation features.
+
+```json
+{
+  "features": {
+    "editUrl": "https://github.com/your-org/repo/edit/main/docs",
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `editUrl` | string | Base URL for "Edit this page" links |
+| `showLastUpdated` | boolean | Show last updated date |
+| `showReadingTime` | boolean | Show estimated reading time |
+| `showAuthors` | boolean | Show author information |
+| `showTags` | boolean | Show document tags |
+| `versioning` | boolean | Enable version switcher |
+
+## Environment Variables
+
+Define custom environment variables that can be used in your MDX content:
+
+```json
+{
+  "env": {
+    "API_BASE_URL": "https://api.example.com",
+    "API_VERSION": "v1"
+  }
+}
+```
+
+Use them in MDX with `${VARIABLE_NAME}` or `{{VARIABLE_NAME}}` syntax:
+
+```mdx
+The API is available at ${API_BASE_URL}/users
+```
+
+## Banner Configuration
+
+Show a site-wide banner for announcements.
+
+```json
+{
+  "banner": {
+    "enabled": true,
+    "message": "🎉 Version 2.0 is now available!",
+    "type": "info",
+    "dismissible": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | boolean | Show/hide the banner |
+| `message` | string | Banner message text |
+| `type` | `"info" \| "warning" \| "error"` | Banner style |
+| `dismissible` | boolean | Allow users to dismiss |
+
+## Footer Configuration
+
+Customize the footer links.
+
+```json
+{
+  "footer": {
+    "copyright": "© 2024 Your Organization",
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          { "label": "Getting Started", "href": "/docs/v1.0.0/getting-started" }
+        ]
+      }
+    ]
+  }
+}
+```

package/templates/minimal/docs/v1.0.0/features.mdx

@@ -0,0 +1,197 @@
+---
+title: Features
+description: Explore all the features of the Specra documentation platform
+sidebar_position: 4
+icon: scroll-text
+---
+
+## Content Features
+
+### MDX Support
+
+Write documentation in MDX—Markdown with React components built in.
+
+```mdx
+# Hello World
+
+This is **Markdown** with a <Badge variant="success">React component</Badge>!
+```
+
+<Callout type="tip">
+MDX lets you create interactive, dynamic documentation that goes beyond static text.
+</Callout>
+
+### Syntax Highlighting
+
+Code blocks automatically get syntax highlighting with line numbers:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function greetUser(user: User): string {
+  return `Hello, ${user.name}!`;
+}
+```
+
+Supported languages include JavaScript, TypeScript, Python, Bash, JSON, CSS, and many more.
+
+### Math Equations
+
+Render mathematical equations using KaTeX:
+
+Inline: <Math>{"E = mc^2"}</Math>
+
+Block:
+<Math block>
+  {"\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}"}
+</Math>
+
+### Mermaid Diagrams
+
+Create diagrams from text using Mermaid:
+
+<Mermaid
+  chart={`
+    graph LR
+      A[Write MDX] --> B[Build]
+      B --> C[Deploy]
+      C --> D[Users Read Docs]
+  `}
+  caption="Documentation workflow"
+/>
+
+## Navigation Features
+
+### Automatic Sidebar
+
+The sidebar is automatically generated from your folder structure. Use `_category_.json` to customize:
+
+```json
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+### Table of Contents
+
+A floating table of contents is automatically generated from your headings. It highlights the current section as you scroll.
+
+### Breadcrumbs
+
+Breadcrumb navigation helps users understand their location in the documentation hierarchy.
+
+### Version Switcher
+
+Support multiple documentation versions with easy switching:
+
+- `/docs/v1.0.0/getting-started`
+- `/docs/v2.0.0/getting-started`
+- `/docs/next/getting-started` (unreleased)
+
+## Search
+
+### Full-Text Search
+
+Powered by Meilisearch for instant, typo-tolerant search results.
+
+- **Keyboard shortcut**: Press `⌘K` or `Ctrl+K` to open search
+- **Typo tolerance**: Finds results even with spelling mistakes
+- **Highlighted results**: See where your query matches
+
+### Search Indexing
+
+Documentation is automatically indexed at build time for fast search.
+
+## Theme & Styling
+
+### Dark Mode
+
+Automatic dark mode that respects system preferences:
+
+- Light mode
+- Dark mode  
+- System preference (auto)
+
+Toggle with the button in the header.
+
+### Customizable Design
+
+All styling is based on CSS variables and Tailwind, making customization easy:
+
+```css
+:root {
+  --primary: oklch(0.55 0.22 264.376);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+}
+```
+
+## Components
+
+### Rich Component Library
+
+Built-in components for common documentation patterns:
+
+<CardGrid cols={3}>
+  <Card icon="message-square" title="Callouts" description="Info, warning, tip, error alerts" />
+  <Card icon="layers" title="Tabs" description="Tabbed content sections" />
+  <Card icon="list" title="Steps" description="Step-by-step guides" />
+  <Card icon="chevrons-up-down" title="Accordion" description="Collapsible content" />
+  <Card icon="grid" title="Cards" description="Feature cards with icons" />
+  <Card icon="code" title="Code Blocks" description="Syntax highlighted code" />
+</CardGrid>
+
+See the [Components](/docs/v1.0.0/components) section for documentation on each component.
+
+## Developer Experience
+
+### Hot Reload
+
+Changes to MDX files are instantly reflected without a full page refresh.
+
+### Frontmatter Validation
+
+Frontmatter fields are validated at build time to catch errors early.
+
+### SEO Optimization
+
+Automatic meta tags, OpenGraph images, and structured data from frontmatter:
+
+- Title and description tags
+- OpenGraph and Twitter cards
+- Canonical URLs
+- Sitemap generation
+
+### Reading Time
+
+Automatic calculation and display of estimated reading time for each page.
+
+## Production Features
+
+### Static Generation
+
+All pages are pre-rendered at build time for maximum performance:
+
+- Zero JavaScript required for content
+- Edge caching friendly
+- Fast Time to First Byte (TTFB)
+
+### Performance
+
+- Lighthouse score: 90+ (desktop)
+- Lazy-loaded images with Next.js Image
+- Code splitting for components
+
+### Accessibility
+
+- Keyboard navigation
+- Screen reader support
+- High contrast support
+- Focus management

package/templates/minimal/docs/v1.0.0/getting-started.mdx

@@ -0,0 +1,183 @@
+---
+title: Getting Started
+description: Set up and start writing documentation with Specra
+sidebar_position: 2
+icon: book
+tab_group: guides
+---
+
+## Prerequisites
+
+Before you begin, make sure you have:
+- Node.js 18+ installed
+- A package manager (npm, yarn, or pnpm)
+
+## Quick Start
+
+<Steps>
+  <Step title="Clone the Repository">
+    ```bash
+    git clone https://github.com/your-org/specra-docs.git
+    cd specra-docs
+    ```
+  </Step>
+  
+  <Step title="Install Dependencies">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+npm install
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+yarn install
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+pnpm install
+```
+      </Tab>
+    </Tabs>
+  </Step>
+  
+  <Step title="Start Development 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>
+
+    Open [http://localhost:3000](http://localhost:3000) to view your docs.
+  </Step>
+</Steps>
+
+## Creating Documentation
+
+<Callout type="warning">
+All documentation files **must use the `.mdx` extension**, not `.md`. MDX enables React components inside your markdown.
+</Callout>
+
+### File Structure
+
+Documentation lives in the `docs/` folder, organized by version:
+
+```txt
+docs/
+├── v1.0.0/               # Version 1.0.0 docs
+│   ├── about.mdx
+│   ├── getting-started.mdx
+│   └── guides/
+│       ├── _category_.json
+│       └── writing-content.mdx
+├── v2.0.0/               # Version 2.0.0 docs
+│   └── ...
+└── next/                 # Unreleased/development docs
+    └── ...
+```
+
+### Creating a New Page
+
+1. Create a new `.mdx` file in the appropriate folder
+2. Add frontmatter at the top of the file
+3. Write your content using Markdown and components
+
+**Example: `docs/v1.0.0/my-page.mdx`**
+
+```mdx
+---
+title: My Page Title
+description: A brief description for SEO
+sidebar_position: 5
+---
+
+# My Page Title
+
+Your content goes here. You can use **Markdown** 
+and <Badge>React components</Badge>.
+```
+
+## Frontmatter
+
+Every MDX file should have frontmatter at the top. Here are the available fields:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | ✅ | Page title (used in sidebar and browser tab) |
+| `description` | Recommended | Short description for SEO meta tags |
+| `sidebar_position` | No | Order in the sidebar (lower = higher) |
+| `tab_group` | No | Tab group name |
+| `tags` | No | Array of tags for categorization |
+| `draft` | No | Set `true` to hide in production |
+| `last_updated` | No | Date string for "last updated" display |
+
+<Callout type="tip">
+Use `sidebar_position` to control the order of pages in the sidebar. Pages are sorted by this number, then alphabetically.
+</Callout>
+
+## Organizing with Folders
+
+Create folders to group related documentation:
+
+```
+docs/v1.0.0/
+├── guides/
+│   ├── _category_.json    # Configure folder display
+│   ├── index.mdx          # Optional: custom folder landing page
+│   ├── installation.mdx
+│   └── configuration.mdx
+```
+
+### Category Configuration
+
+Create `_category_.json` in a folder to customize its sidebar appearance:
+
+```json
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+## Using Components
+
+Specra includes many built-in components. Import is automatic—just use them:
+
+```mdx
+<Callout type="info">
+  This is an info callout!
+</Callout>
+
+<Tabs defaultValue="JavaScript">
+  <Tab label="JavaScript">
+    JavaScript code here
+  </Tab>
+  <Tab label="Python">
+    Python code here
+  </Tab>
+</Tabs>
+```
+
+See the [Components](/docs/v1.0.0/components) section for all available components.
+
+## Next Steps
+
+<CardGrid cols={2}>
+  <Card icon="settings" title="Configuration" description="Customize your docs site" href="/docs/v1.0.0/configuration" />
+  <Card icon="layers" title="Features" description="Explore all platform features" href="/docs/v1.0.0/features" />
+</CardGrid>