@alliance-droid/svelte-docs-system 0.0.1

package/template-starter/docs/guides/vercel-deployment.md

@@ -0,0 +1,131 @@
+---
+title: Deploy to Vercel
+description: Deploy your documentation site to Vercel in minutes
+---
+
+# Vercel Deployment
+
+Deploy your documentation site to Vercel with automatic updates from Git.
+
+## Prerequisites
+
+- GitHub account and repository with your docs
+- Vercel account (free at https://vercel.com)
+
+## Step-by-Step Guide
+
+### 1. Push Your Code to GitHub
+
+If you haven't already:
+
+```bash
+git add .
+git commit -m "Initial commit"
+git push origin main
+```
+
+### 2. Import Project to Vercel
+
+1. Go to https://vercel.com/new
+2. Select "Import Git Repository"
+3. Find and select your docs repository
+4. Click "Import"
+
+### 3. Configure Build Settings
+
+Vercel should auto-detect settings. Verify:
+
+- **Framework Preset:** SvelteKit
+- **Build Command:** `npm run build`
+- **Output Directory:** `build`
+- **Environment Variables:** Add any needed `.env` variables
+
+### 4. Deploy
+
+Click "Deploy" and wait for the build to complete.
+
+Your site will be available at `https://your-project.vercel.app`
+
+## Custom Domain
+
+1. Go to project settings → Domains
+2. Add your custom domain
+3. Follow DNS configuration instructions
+4. Wait for DNS to propagate (usually 24 hours)
+
+## Automatic Deployments
+
+Every push to your main branch automatically triggers a new deployment.
+
+Create a preview deployment by pushing to any other branch.
+
+## Environment Variables
+
+Add secrets in Project Settings → Environment Variables:
+
+```
+VITE_API_URL=https://api.example.com
+VITE_PUBLIC_KEY=your_public_key
+```
+
+## Monitoring Deployments
+
+Check deployment status in the Vercel dashboard:
+- View logs
+- See performance metrics
+- Rollback to previous versions
+
+## Troubleshooting
+
+### Build Fails
+
+Check the build logs in Vercel dashboard for errors.
+
+Common issues:
+- Missing dependencies: Run `npm install` locally first
+- TypeScript errors: Run `npm run check` locally
+- Node version mismatch: Add `.nvmrc` file with Node version
+
+### Site Not Found
+
+- Wait a few minutes for DNS propagation
+- Clear browser cache (Ctrl+Shift+Del)
+- Check domain settings in Vercel dashboard
+
+### Performance Issues
+
+- Review Core Web Vitals in Vercel Analytics
+- Optimize images using the Image component
+- Enable caching in Vercel settings
+
+## Advanced Configuration
+
+### Vercel Configuration File
+
+Create `vercel.json` for advanced settings:
+
+```json
+{
+  "buildCommand": "npm run build",
+  "outputDirectory": "build",
+  "env": {
+    "VITE_API_URL": "@vite_api_url"
+  }
+}
+```
+
+### Environment Variables from Secrets
+
+Use Vercel Secrets for sensitive data:
+
+```bash
+vercel env add VITE_API_KEY
+```
+
+Then reference in deployment settings.
+
+## Next Steps
+
+- Set up analytics to track documentation usage
+- Configure custom error pages
+- Enable preview deployments for pull requests

package/template-starter/docs/index.md

@@ -0,0 +1,49 @@
+---
+title: Documentation Home
+description: Welcome to your documentation site
+---
+
+# Welcome to Your Documentation
+
+This is the main landing page for your documentation. Edit this file at `docs/index.md` to customize your documentation home page.
+
+## Getting Started
+
+1. **Add documentation files** - Create `.md` files in the `docs/` folder
+2. **Organize with folders** - Use folders to organize documentation by topic (e.g., `docs/guides/`, `docs/api/`)
+3. **Update configuration** - Edit `docs/_config.json` to customize navigation and branding
+4. **Deploy** - Build and deploy your docs site
+
+## Documentation Structure
+
+Your documentation can be organized like this:
+
+```
+docs/
+├── index.md              → Home page (/docs)
+├── setup.md              → /docs/setup
+├── guides/
+│   ├── getting-started.md → /docs/guides/getting-started
+│   └── configuration.md   → /docs/guides/configuration
+├── api/
+│   ├── overview.md        → /docs/api/overview
+│   └── reference.md       → /docs/api/reference
+└── _config.json           → Navigation configuration
+```
+
+## Features
+
+- **Markdown Support** - Write docs in simple markdown
+- **Folder-Based Routing** - Folder structure automatically becomes navigation
+- **Dark Mode** - Built-in light/dark theme support
+- **Search** - Full-text search across all documentation
+- **Responsive Design** - Mobile-friendly documentation site
+- **Custom Components** - Use interactive Svelte components in your docs
+
+## Next Steps
+
+- Check out the [Setup Guide](./setup.md) for installation instructions
+- Read the [Configuration Guide](./guides/configuration.md) to customize your docs
+- Explore [Components](./api/components.md) to learn about available UI elements
+
+Happy documenting! 📚

package/template-starter/docs/setup.md

@@ -0,0 +1,149 @@
+---
+title: Setup Guide
+description: Get started with your documentation site in minutes
+---
+
+# Setup Guide
+
+Get your documentation site up and running in just a few minutes.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- npm or pnpm package manager
+
+## Installation
+
+1. **Clone or create from template**
+   ```bash
+   git clone <your-repo>
+   cd docs-starter
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   # or
+   pnpm install
+   ```
+
+3. **Start the development server**
+   ```bash
+   npm run dev
+   ```
+
+4. **Open in browser**
+   Visit `http://localhost:5173` to see your documentation site
+
+## Project Structure
+
+```
+docs-starter/
+├── docs/                  # Your documentation files
+│   ├── index.md          # Home page
+│   ├── setup.md          # This file
+│   ├── guides/           # Guide documentation
+│   ├── api/              # API reference
+│   └── _config.json      # Navigation configuration
+├── src/                  # Source code
+│   ├── routes/           # SvelteKit routes
+│   ├── lib/              # Reusable components
+│   └── app.css           # Global styles
+└── package.json          # Project dependencies
+```
+
+## Development
+
+### Running the dev server
+
+```bash
+npm run dev
+```
+
+The site will hot-reload when you edit files.
+
+### Building for production
+
+```bash
+npm run build
+```
+
+This creates an optimized production build in the `build/` folder.
+
+### Preview production build
+
+```bash
+npm run preview
+```
+
+### Type checking
+
+```bash
+npm run check
+```
+
+## Customization
+
+### Add documentation
+
+Create new markdown files in the `docs/` folder:
+
+```bash
+docs/
+├── guides/
+│   ├── getting-started.md
+│   ├── advanced-usage.md
+│   └── troubleshooting.md
+└── api/
+    ├── overview.md
+    └── reference.md
+```
+
+### Configure navigation
+
+Edit `docs/_config.json` to customize the sidebar navigation:
+
+```json
+{
+  "name": "My Docs",
+  "sections": [
+    {
+      "title": "Getting Started",
+      "pages": [
+        { "label": "Setup", "path": "/docs/setup" },
+        { "label": "Quick Start", "path": "/docs/guides/getting-started" }
+      ]
+    }
+  ]
+}
+```
+
+### Customize styling
+
+Edit `tailwind.config.ts` and `src/app.css` to match your brand colors and typography.
+
+## Deployment
+
+Your documentation site can be deployed to:
+
+- **Vercel** - See [Vercel Deployment Guide](./guides/vercel-deployment.md)
+- **Netlify** - See [Netlify Deployment Guide](./guides/netlify-deployment.md)
+- **GitHub Pages** - See [GitHub Pages Deployment Guide](./guides/github-pages-deployment.md)
+
+## Troubleshooting
+
+### Build fails
+- Clear `.svelte-kit/` folder and rebuild: `rm -rf .svelte-kit/ && npm run build`
+- Check for TypeScript errors: `npm run check`
+
+### Port already in use
+- Change port in `vite.config.ts`
+- Or kill existing process: `lsof -ti:5173 | xargs kill -9`
+
+### Dependencies issue
+- Delete `node_modules/` and `package-lock.json`
+- Reinstall: `npm install`
+
+## Need Help?
+
+Check the guides and API reference in the documentation, or consult the official SvelteKit documentation at https://kit.svelte.dev

package/template-starter/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "docs-starter",
+  "description": "A documentation site built with Svelte Docs System",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && pagefind --site build || echo 'Pagefind indexing skipped'",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@tailwindcss/postcss": "^4.1.18",
+    "pagefind": "^1.4.0",
+    "postcss": "^8.5.6",
+    "svelte": "^5.48.2",
+    "svelte-check": "^4.3.5",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "marked": "^17.0.1"
+  }
+}

package/template-starter/pagefind.toml

@@ -0,0 +1,3 @@
+# Pagefind configuration
+output_path = "build/pagefind"
+site_url = "/"

package/template-starter/postcss.config.js

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {}
+  }
+};

package/template-starter/src/app.css

@@ -0,0 +1,34 @@
+@import "tailwindcss";
+
+@layer base {
+  :root {
+    color-scheme: light;
+  }
+
+  :root.dark {
+    color-scheme: dark;
+  }
+
+  html {
+    @apply antialiased scroll-smooth;
+  }
+
+  body {
+    @apply bg-white dark:bg-slate-950 text-slate-900 dark:text-slate-100 transition-colors;
+  }
+}
+
+@layer components {
+  .doc-container {
+    @apply max-w-7xl mx-auto;
+  }
+
+  .doc-content {
+    @apply max-w-none;
+  }
+}
+
+/* Smooth transitions */
+* {
+  @apply transition-colors duration-200;
+}

package/template-starter/src/app.d.ts

@@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};

package/template-starter/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/template-starter/src/lib/components/APITable.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+  /**
+   * API Reference Table component
+   * Displays API documentation in a clean, organized table format
+   */
+
+  interface Column {
+    key: string;
+    label: string;
+    width?: string;
+  }
+
+  interface Row {
+    [key: string]: string | number | boolean | null;
+  }
+
+  interface Props {
+    columns: Column[];
+    rows: Row[];
+    title?: string;
+    description?: string;
+  }
+
+  let { columns, rows, title, description }: Props = $props();
+</script>
+
+<div class="my-6">
+  {#if title}
+    <h3 class="mb-2 text-lg font-bold text-gray-900 dark:text-white">{title}</h3>
+  {/if}
+
+  {#if description}
+    <p class="mb-4 text-gray-600 dark:text-gray-400">{description}</p>
+  {/if}
+
+  <div class="overflow-x-auto rounded-lg border border-gray-200 dark:border-gray-700">
+    <table class="w-full text-sm">
+      <thead class="bg-gray-100 dark:bg-gray-800">
+        <tr>
+          {#each columns as column}
+            <th
+              class="px-4 py-3 text-left font-semibold text-gray-900 dark:text-gray-100"
+              style={column.width ? `width: ${column.width}` : ''}
+            >
+              {column.label}
+            </th>
+          {/each}
+        </tr>
+      </thead>
+      <tbody>
+        {#each rows as row, rowIndex}
+          <tr class="border-t border-gray-200 dark:border-gray-700 {rowIndex % 2 === 0 ? 'bg-white dark:bg-gray-900' : 'bg-gray-50 dark:bg-gray-800/50'}">
+            {#each columns as column}
+              <td class="px-4 py-3 text-gray-800 dark:text-gray-300">
+                <div class="break-words font-mono text-xs">
+                  {#if typeof row[column.key] === 'boolean'}
+                    <span class="inline-block rounded bg-gray-200 px-2 py-1 dark:bg-gray-700">
+                      {row[column.key] ? 'true' : 'false'}
+                    </span>
+                  {:else if row[column.key] === null}
+                    <span class="text-gray-400 dark:text-gray-500">null</span>
+                  {:else}
+                    {row[column.key]}
+                  {/if}
+                </div>
+              </td>
+            {/each}
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  </div>
+
+  {#if rows.length === 0}
+    <div class="py-8 text-center text-gray-500 dark:text-gray-400">
+      No data available
+    </div>
+  {/if}
+</div>
+
+<style>
+  table {
+    width: 100%;
+    border-collapse: collapse;
+  }
+
+  thead {
+    background-color: #f3f4f6;
+  }
+
+  :global(.dark) thead {
+    background-color: #1f2937;
+  }
+
+  th {
+    border-bottom: 1px solid #e5e7eb;
+    padding: 0.75rem 1rem;
+    text-align: left;
+    font-weight: 600;
+    color: #111827;
+  }
+
+  :global(.dark) th {
+    border-bottom-color: #374151;
+    color: #f3f4f6;
+  }
+
+  td {
+    border-bottom: 1px solid #e5e7eb;
+    padding: 0.75rem 1rem;
+  }
+
+  :global(.dark) td {
+    border-bottom-color: #374151;
+  }
+
+  tbody tr:last-child td {
+    border-bottom: none;
+  }
+</style>

package/template-starter/src/lib/components/APITable.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/svelte';
+import APITable from './APITable.svelte';
+
+describe('APITable Component', () => {
+  it('renders table with columns', () => {
+    const columns = [
+      { key: 'name', label: 'Name' },
+      { key: 'type', label: 'Type' }
+    ];
+    const rows = [{ name: 'param1', type: 'string' }];
+
+    const { container } = render(APITable, { props: { columns, rows } });
+
+    expect(container.querySelector('table')).toBeTruthy();
+    expect(screen.getByText('Name')).toBeTruthy();
+    expect(screen.getByText('Type')).toBeTruthy();
+  });
+});

package/template-starter/src/lib/components/Breadcrumbs.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+  /**
+   * Breadcrumbs navigation component
+   * Shows the current page path for easy navigation
+   */
+
+  interface BreadcrumbItem {
+    label: string;
+    href?: string;
+  }
+
+  interface Props {
+    items: BreadcrumbItem[];
+  }
+
+  let { items }: Props = $props();
+</script>
+
+<nav aria-label="Breadcrumb" class="mb-6">
+  <ol class="flex items-center gap-2 text-sm">
+    {#each items as item, index}
+      <li class="flex items-center gap-2">
+        {#if item.href && index < items.length - 1}
+          <a
+            href={item.href}
+            class="text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300"
+          >
+            {item.label}
+          </a>
+        {:else}
+          <span class={index === items.length - 1 ? 'font-semibold text-gray-900 dark:text-white' : 'text-gray-600 dark:text-gray-400'}>
+            {item.label}
+          </span>
+        {/if}
+
+        {#if index < items.length - 1}
+          <i class="fa-solid fa-chevron-right text-gray-400 dark:text-gray-500"></i>
+        {/if}
+      </li>
+    {/each}
+  </ol>
+</nav>
+
+<style>
+  nav {
+    margin-bottom: 1.5rem;
+    font-size: 0.875rem;
+  }
+
+  ol {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  li {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  a {
+    color: #2563eb;
+  }
+
+  a:hover {
+    color: #1d4ed8;
+  }
+
+  :global(.dark) a {
+    color: #60a5fa;
+  }
+
+  :global(.dark) a:hover {
+    color: #93c5fd;
+  }
+
+  span {
+    color: #4b5563;
+  }
+
+  :global(.dark) span {
+    color: #9ca3af;
+  }
+</style>

package/template-starter/src/lib/components/Breadcrumbs.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/svelte';
+import Breadcrumbs from './Breadcrumbs.svelte';
+
+describe('Breadcrumbs Component', () => {
+  it('renders all breadcrumb items', () => {
+    const items = [
+      { label: 'Home', href: '/' },
+      { label: 'Docs', href: '/docs' },
+      { label: 'API' }
+    ];
+
+    render(Breadcrumbs, { props: { items } });
+
+    expect(screen.getByText('Home')).toBeTruthy();
+    expect(screen.getByText('Docs')).toBeTruthy();
+    expect(screen.getByText('API')).toBeTruthy();
+  });
+});