create-specra 0.1.6 → 0.2.0

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>

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

@@ -0,0 +1,81 @@
+---
+title: Themes
+description: Configure the look and feel of your documentation site
+sidebar_position: 1
+---
+
+The platform supports light and dark themes out of the box, with full control over which mode is used by default.
+
+## Theme Modes
+
+Three theme modes are available:
+
+| Mode | Description |
+|------|-------------|
+| `light` | Always use the light theme |
+| `dark` | Always use the dark theme |
+| `system` | Follow the user's operating system preference |
+
+## Configuration
+
+Set the default theme in `specra.config.json`:
+
+```json
+{
+  "theme": {
+    "defaultMode": "dark",
+    "respectPrefersColorScheme": true
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultMode` | `"light" \| "dark" \| "system"` | `"system"` | Initial theme mode |
+| `respectPrefersColorScheme` | `boolean` | `true` | Whether to detect and follow OS preference |
+
+<Callout type="info">
+  When `respectPrefersColorScheme` is `true` and `defaultMode` is `"system"`, the site automatically switches themes when the user changes their OS appearance settings.
+</Callout>
+
+## Theme Toggle
+
+Users can switch themes using the toggle button in the site header. Their preference is saved in local storage and persists across visits.
+
+## Customizing Colors
+
+All colors are defined as CSS custom properties, making them easy to override:
+
+```css
+:root {
+  --primary: oklch(0.55 0.22 264.376);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+}
+
+.dark {
+  --primary: oklch(0.65 0.22 264.376);
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.95 0 0);
+}
+```
+
+<Callout type="tip">
+  Use the OKLCH color space for perceptually uniform color adjustments. This ensures colors look consistent across light and dark themes.
+</Callout>
+
+## Best Practices
+
+<Steps>
+  <Step title="Choose a Default">
+    Pick a default theme that matches your brand. For developer documentation, dark mode is often preferred.
+  </Step>
+
+  <Step title="Test Both Themes">
+    Always preview your content in both light and dark modes. Ensure images, diagrams, and code blocks are readable in both.
+  </Step>
+
+  <Step title="Respect User Preference">
+    Keep `respectPrefersColorScheme` enabled so users get the theme they expect.
+  </Step>
+</Steps>

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

@@ -0,0 +1,39 @@
+---
+title: Introduction
+description: Welcome to the documentation
+sidebar_position: 1
+icon: book
+---
+
+Welcome to the v2 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/v2.0.0/quickstart" />
+  <Card icon="book-open" title="Core Concepts" description="Understand the key ideas behind the platform" href="/docs/v2.0.0/concepts" />
+  <Card icon="file-text" title="Content Guide" description="Learn how to write and organize content" href="/docs/v2.0.0/content/formatting" />
+  <Card icon="palette" title="Customization" description="Themes, branding, and design options" href="/docs/v2.0.0/customization/themes" />
+</CardGrid>
+
+## Overview
+
+This documentation platform gives you a modern, fast, and beautiful docs experience out of the box. In v2 we've improved performance and added new customization options.
+
+- **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 in v2
+
+| Feature | Description |
+|---------|-------------|
+| **Improved Performance** | Faster page loads and smaller bundle sizes |
+| **New Customization** | More control over themes and branding |
+| **Better Navigation** | Enhanced sidebar and breadcrumb experience |

package/templates/book-docs/docs/v2.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/          # Previous version docs
+│   └── v2.0.0/          # Current version docs
+├── 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/v2.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/v2.0.0/concepts" />
+  <Card icon="file-text" title="Formatting" description="Style your content" href="/docs/v2.0.0/content/formatting" />
+</CardGrid>

package/templates/book-docs/gitignore

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

package/templates/book-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/book-docs/postcss.config.mjs

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