@alliance-droid/svelte-docs-system 0.0.1

package/template-starter/README.md

@@ -0,0 +1,320 @@
+# 📚 Svelte Documentation Starter
+
+A professional, production-ready documentation site template built with SvelteKit and Tailwind CSS.
+
+## ✨ Features
+
+- ⚡ **Lightning Fast** - Pre-rendered static site with Vite
+- 🎨 **Beautiful Design** - Professional theme with light/dark mode
+- 🔍 **Full-Text Search** - Powered by Pagefind
+- 📱 **Responsive** - Mobile-friendly documentation
+- ♿ **Accessible** - WCAG compliant
+- 🚀 **Easy Deployment** - Deploy to Vercel, Netlify, GitHub Pages, or anywhere
+- 📝 **Markdown-Based** - Write docs in simple Markdown
+- 🎯 **Zero Config** - Folder structure becomes navigation automatically
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- npm or pnpm
+
+### Installation
+
+```bash
+# Clone this repository
+git clone <your-repo>
+cd docs-starter
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+Open `http://localhost:5173` in your browser.
+
+## 📖 Project Structure
+
+```
+docs-starter/
+├── docs/                      # Your documentation files
+│   ├── index.md              # Home page
+│   ├── setup.md              # Setup guide
+│   ├── guides/               # Guide documentation
+│   │   ├── configuration.md
+│   │   ├── vercel-deployment.md
+│   │   ├── netlify-deployment.md
+│   │   └── github-pages-deployment.md
+│   ├── api/                  # API reference
+│   │   ├── overview.md
+│   │   └── components.md
+│   └── _config.json          # Navigation configuration
+├── src/                      # Source code
+│   ├── routes/               # SvelteKit routes
+│   ├── lib/                  # Reusable components
+│   └── app.css              # Global styles
+├── .github/
+│   └── workflows/           # CI/CD workflows
+├── static/                  # Static assets
+└── package.json            # Project dependencies
+```
+
+## 📝 Adding Documentation
+
+1. Create a markdown file in the `docs/` folder:
+
+```markdown
+---
+title: My Guide
+description: A guide to something amazing
+---
+
+# My Guide
+
+Your content here...
+```
+
+2. File structure becomes navigation:
+   - `docs/setup.md` → `/docs/setup`
+   - `docs/guides/intro.md` → `/docs/guides/intro`
+   - Nested folders work at any depth
+
+3. Customize navigation in `docs/_config.json`
+
+## 🎨 Customization
+
+### Colors and Styling
+
+Edit `tailwind.config.ts`:
+
+```typescript
+theme: {
+  extend: {
+    colors: {
+      primary: '#3b82f6',
+      secondary: '#8b5cf6'
+    }
+  }
+}
+```
+
+### Navigation Structure
+
+Configure `docs/_config.json`:
+
+```json
+{
+  "name": "My Docs",
+  "sections": [
+    {
+      "title": "Getting Started",
+      "pages": [
+        { "label": "Setup", "path": "/docs/setup" }
+      ]
+    }
+  ]
+}
+```
+
+### Environment Variables
+
+Create `.env` file:
+
+```bash
+VITE_API_URL=https://api.example.com
+VITE_SITE_NAME=My Documentation
+```
+
+## 🔨 Available Scripts
+
+```bash
+npm run dev       # Start development server
+npm run build     # Build for production
+npm run preview   # Preview production build
+npm run check     # Type check and lint
+```
+
+## 🚀 Deployment
+
+### GitHub Pages (Free)
+
+```bash
+git push origin main
+```
+
+Workflow defined in `.github/workflows/deploy-github-pages.yml`
+
+See the [GitHub Pages Deployment Guide](./docs/guides/github-pages-deployment.md)
+
+### Vercel
+
+1. Push to GitHub
+2. Import project at https://vercel.com/new
+3. Select this repository
+4. Deploy!
+
+See the [Vercel Deployment Guide](./docs/guides/vercel-deployment.md)
+
+### Netlify
+
+1. Push to GitHub
+2. Connect at https://app.netlify.com
+3. Select this repository
+4. Deploy!
+
+See the [Netlify Deployment Guide](./docs/guides/netlify-deployment.md)
+
+## 📚 Built-in Components
+
+### Callout
+
+```svelte
+<Callout variant="info" title="Note">
+  This is important information.
+</Callout>
+```
+
+### CodeBlock
+
+```svelte
+<CodeBlock code="const x = 42;" language="javascript" />
+```
+
+### Tabs
+
+```svelte
+<Tabs items={[
+  { label: 'JS', content: '<code>const x = 42;</code>' },
+  { label: 'TS', content: '<code>const x: number = 42;</code>' }
+]} />
+```
+
+### APITable
+
+```svelte
+<APITable
+  columns={[
+    { key: 'name', label: 'Name' },
+    { key: 'type', label: 'Type' }
+  ]}
+  rows={[
+    { name: 'param', type: 'string' }
+  ]}
+/>
+```
+
+See [Components Documentation](./docs/api/components.md) for all available components.
+
+## 🔍 Search
+
+Full-text search is automatically enabled:
+- Press `Cmd+K` or `Ctrl+K` to search
+- Search across all documentation
+- Results update in real-time
+
+## 🌙 Dark Mode
+
+Dark mode toggle is built-in:
+- Click the moon/sun icon in the header
+- Respects system preference
+- Smooth transitions between themes
+
+## 🧪 Testing
+
+Add your test files alongside component files:
+
+```bash
+src/
+├── lib/
+│   ├── components/
+│   │   ├── Callout.svelte
+│   │   └── Callout.test.ts
+```
+
+Run tests:
+
+```bash
+npm run test
+```
+
+## 📖 Documentation Structure
+
+See guides for more details:
+
+- [Setup Guide](./docs/setup.md) - Installation and getting started
+- [Configuration Guide](./docs/guides/configuration.md) - Customize your docs
+- [Components Guide](./docs/api/components.md) - Available components
+
+## 🎯 Best Practices
+
+### Writing Documentation
+
+- Use clear, concise headings
+- Include code examples for every feature
+- Use Callout components for important notes
+- Add screenshots for visual features
+- Link to related documentation
+
+### Organization
+
+- Group related docs in folders
+- Use consistent naming (kebab-case)
+- Update `_config.json` when adding sections
+- Keep folder depth reasonable (2-3 levels)
+
+### Deployment
+
+- Test build locally: `npm run build`
+- Use preview deployment for PRs
+- Monitor build logs for errors
+- Keep dependencies updated
+
+## 🐛 Troubleshooting
+
+### Build fails
+
+```bash
+# Clear cache and rebuild
+rm -rf .svelte-kit
+npm run build
+```
+
+### Port already in use
+
+```bash
+# Change port in vite.config.ts
+# Or kill process: lsof -ti:5173 | xargs kill -9
+```
+
+### Search not working
+
+- Run build: `npm run build`
+- Search is only available in production builds
+
+## 📦 Tech Stack
+
+- **Framework:** SvelteKit 2.x
+- **UI Framework:** Svelte 5
+- **Styling:** Tailwind CSS
+- **Build Tool:** Vite
+- **Search:** Pagefind
+- **Deployment:** Static adapter (adapter-static)
+
+## 📄 License
+
+This template is provided as-is for your use.
+
+## 🤝 Contributing
+
+Feel free to customize this template for your needs!
+
+## 📞 Support
+
+For detailed guides and documentation, see the `docs/` folder.
+
+---
+
+**Happy documenting!** 📚✨

package/template-starter/docs/_config.json

@@ -0,0 +1,39 @@
+{
+  "name": "Documentation Starter",
+  "baseUrl": "/docs",
+  "description": "A documentation site built with Svelte Docs System",
+  "logo": "/logo.svg",
+  "sections": [
+    {
+      "title": "Getting Started",
+      "pages": [
+        { "label": "Home", "path": "/docs" },
+        { "label": "Setup", "path": "/docs/setup" }
+      ]
+    },
+    {
+      "title": "Guides",
+      "pages": [
+        { "label": "Configuration", "path": "/docs/guides/configuration" },
+        { "label": "Vercel Deployment", "path": "/docs/guides/vercel-deployment" },
+        { "label": "Netlify Deployment", "path": "/docs/guides/netlify-deployment" },
+        { "label": "GitHub Pages", "path": "/docs/guides/github-pages-deployment" }
+      ]
+    },
+    {
+      "title": "API Reference",
+      "pages": [
+        { "label": "Overview", "path": "/docs/api/overview" },
+        { "label": "Components", "path": "/docs/api/components" }
+      ]
+    }
+  ],
+  "sidebar": {
+    "collapsible": true,
+    "showToc": true
+  },
+  "footer": {
+    "showLastUpdated": true,
+    "showEditLink": false
+  }
+}

package/template-starter/docs/api/components.md

@@ -0,0 +1,257 @@
+---
+title: Available Components
+description: Built-in Svelte components for documentation
+---
+
+# Available Components
+
+This documentation site includes several pre-built Svelte components for enhanced documentation experiences.
+
+## Callout
+
+Display informational messages with different variants.
+
+```svelte
+<Callout variant="info" title="Information">
+  This is an informational message.
+</Callout>
+
+<Callout variant="warning" title="Warning">
+  This is a warning message.
+</Callout>
+
+<Callout variant="success" title="Success">
+  This is a success message.
+</Callout>
+
+<Callout variant="error" title="Error">
+  This is an error message.
+</Callout>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| variant | 'info' \| 'warning' \| 'success' \| 'error' | true | Style variant |
+| title | string | false | Optional title |
+| children | HTMLContent | true | Message content |
+
+## CodeBlock
+
+Syntax-highlighted code blocks with copy functionality.
+
+```svelte
+<CodeBlock
+  code={`const greeting = 'Hello, World!';
+console.log(greeting);`}
+  language="javascript"
+  filename="example.js"
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| code | string | true | Code content |
+| language | string | true | Language (js, ts, python, etc) |
+| filename | string | false | Optional filename display |
+
+## Tabs
+
+Display tabbed content with easy switching.
+
+```svelte
+<Tabs items={[
+  { label: 'JavaScript', content: '<code>const x = 42;</code>' },
+  { label: 'Python', content: '<code>x = 42</code>' },
+  { label: 'Rust', content: '<code>let x = 42;</code>' }
+]} />
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| items | Tab[] | true | Array of tab items |
+
+### Tab Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| label | string | Tab title |
+| content | string | HTML content |
+
+## APITable
+
+Display API reference tables with consistent formatting.
+
+```svelte
+<APITable
+  title="Function Parameters"
+  columns={[
+    { key: 'name', label: 'Parameter Name' },
+    { key: 'type', label: 'Type' },
+    { key: 'description', label: 'Description' }
+  ]}
+  rows={[
+    { name: 'input', type: 'string', description: 'The input text' },
+    { name: 'options', type: 'object', description: 'Configuration options' }
+  ]}
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| title | string | false | Optional table title |
+| columns | Column[] | true | Column definitions |
+| rows | any[] | true | Table data rows |
+
+## Image
+
+Optimized image display with optional captions and zoom.
+
+```svelte
+<Image
+  src="/images/screenshot.png"
+  alt="Screenshot"
+  caption="Figure 1: Main dashboard"
+  zoomable={true}
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| src | string | true | Image URL |
+| alt | string | true | Alt text for accessibility |
+| caption | string | false | Optional caption |
+| zoomable | boolean | false | Enable click to zoom |
+
+## Breadcrumbs
+
+Navigation breadcrumbs showing current page location.
+
+```svelte
+<Breadcrumbs items={[
+  { label: 'Home', href: '/' },
+  { label: 'Guides', href: '/guides' },
+  { label: 'Setup' }
+]} />
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| items | BreadcrumbItem[] | true | Breadcrumb items |
+
+### BreadcrumbItem
+
+| Property | Type | Description |
+|----------|------|-------------|
+| label | string | Display text |
+| href | string | Optional link URL |
+
+## Search
+
+Full-text search component (automatically included in layout).
+
+### Features
+
+- Type to search across all documentation
+- Keyboard shortcut: `Cmd+K` / `Ctrl+K`
+- Highlight matching results
+- Fast client-side search
+
+## Navbar
+
+Top navigation bar (automatically included).
+
+### Features
+
+- Logo and site title
+- Theme toggle (light/dark mode)
+- Language switcher (if configured)
+- Search access
+- Mobile menu
+
+## Sidebar
+
+Documentation navigation sidebar.
+
+### Features
+
+- Folder structure navigation
+- Active page highlighting
+- Collapsible sections
+- Mobile-friendly collapse
+- Custom section ordering
+
+## Footer
+
+Site footer with links and information.
+
+### Features
+
+- Copyright information
+- Social media links
+- Documentation links
+- Last updated timestamp
+
+## Custom Components
+
+Create your own components and use them in markdown:
+
+```svelte
+<!-- Save as src/lib/components/MyComponent.svelte -->
+<script lang="ts">
+  export let title: string;
+  export let items: string[];
+</script>
+
+<div class="my-component">
+  <h3>{title}</h3>
+  <ul>
+    {#each items as item}
+      <li>{item}</li>
+    {/each}
+  </ul>
+</div>
+
+<style>
+  .my-component {
+    padding: 1rem;
+    border: 1px solid #ddd;
+  }
+</style>
+```
+
+Then import and use in your markdown:
+
+```markdown
+---
+title: Example Page
+---
+
+<script>
+  import MyComponent from '$lib/components/MyComponent.svelte';
+</script>
+
+# My Page
+
+<MyComponent title="Items" items={['Item 1', 'Item 2']} />
+```
+
+## Best Practices
+
+- Use Callout for important notes and warnings
+- Use CodeBlock with language highlighting for code examples
+- Use Tabs for language/framework variations
+- Use APITable for API reference documentation
+- Use Image for screenshots and diagrams
+- Keep components simple and focused on content