@alliance-droid/svelte-docs-system 0.0.1

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

@@ -0,0 +1,169 @@
+---
+title: API Overview
+description: Documentation site API and available endpoints
+---
+
+# API Overview
+
+This documentation site provides a clean interface for viewing API documentation.
+
+## Getting Started
+
+The documentation site is built with Svelte and SvelteKit, providing:
+
+- **Fast page loads** - Static pre-rendered pages
+- **Full-text search** - Search across all documentation
+- **Dark mode** - Automatic light/dark theme switching
+- **Mobile responsive** - Works great on all devices
+- **Accessible** - WCAG compliant
+
+## Available Documentation Sections
+
+### Guides
+
+Step-by-step guides for common tasks:
+
+- [Setup Guide](../setup.md) - Get started in minutes
+- [Configuration](../guides/configuration.md) - Customize your docs
+- [Vercel Deployment](../guides/vercel-deployment.md) - Deploy to Vercel
+- [Netlify Deployment](../guides/netlify-deployment.md) - Deploy to Netlify
+- [GitHub Pages](../guides/github-pages-deployment.md) - Deploy to GitHub Pages
+
+### Components
+
+Interactive Svelte components for documentation:
+
+- Callout - Information, warning, success, and error callouts
+- CodeBlock - Syntax-highlighted code with copy button
+- Tabs - Tabbed content display
+- APITable - API reference tables
+- Image - Optimized image display with captions
+- Breadcrumbs - Navigation breadcrumbs
+
+## Features
+
+### Search
+
+Use the search feature to quickly find documentation:
+- Full-text search across all pages
+- Keyboard shortcut: Press `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux)
+- Fast and responsive search results
+
+### Dark Mode
+
+Toggle between light and dark themes:
+- Click the theme toggle in the header
+- Automatically respects your system preference
+- Smooth transitions between themes
+
+### Navigation
+
+- **Sidebar** - Browse documentation structure
+- **Breadcrumbs** - See current location in docs
+- **Previous/Next** - Navigate between pages
+- **Table of Contents** - Jump to sections within a page
+
+## Documentation Format
+
+All documentation is written in **Markdown** with optional YAML frontmatter:
+
+```markdown
+---
+title: Page Title
+description: Brief description for SEO
+---
+
+# Page Title
+
+Your content here...
+```
+
+## Markdown Features
+
+### Headings
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+```
+
+### Code Blocks
+
+````markdown
+```javascript
+const greeting = 'Hello, World!';
+```
+````
+
+### Lists
+
+```markdown
+- Item 1
+- Item 2
+- Item 3
+
+1. First
+2. Second
+3. Third
+```
+
+### Links
+
+```markdown
+[Link text](https://example.com)
+[Relative link](../other-page.md)
+```
+
+### Images
+
+```markdown
+![Alt text](https://example.com/image.jpg)
+```
+
+### Tables
+
+```markdown
+| Column 1 | Column 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+| Cell 3   | Cell 4   |
+```
+
+### Blockquotes
+
+```markdown
+> This is a blockquote
+> It can span multiple lines
+```
+
+## Custom Components
+
+Use Svelte components in your markdown documentation:
+
+```svelte
+<Callout variant="info" title="Tip">
+  This is an informational callout.
+</Callout>
+```
+
+## Contributing
+
+To add new documentation:
+
+1. Create a new `.md` file in the appropriate folder
+2. Add YAML frontmatter with title and description
+3. Write content in Markdown
+4. Build and test: `npm run build`
+5. Deploy using your preferred hosting platform
+
+## Support
+
+For issues or questions:
+- Check existing documentation and guides
+- Search the documentation using the search feature
+- Review component examples in the docs
+
+## License
+
+This documentation template is provided as-is for your use.

package/template-starter/docs/guides/configuration.md

@@ -0,0 +1,145 @@
+---
+title: Configuration Guide
+description: Learn how to configure your documentation site
+---
+
+# Configuration Guide
+
+Customize your documentation site to match your needs.
+
+## Navigation Configuration
+
+Edit `docs/_config.json` to control the sidebar structure:
+
+```json
+{
+  "name": "Your Project Docs",
+  "baseUrl": "/docs",
+  "sections": [
+    {
+      "title": "Getting Started",
+      "pages": [
+        { "label": "Introduction", "path": "/docs/index" },
+        { "label": "Setup", "path": "/docs/setup" }
+      ]
+    },
+    {
+      "title": "Guides",
+      "pages": [
+        { "label": "Configuration", "path": "/docs/guides/configuration" },
+        { "label": "Deployment", "path": "/docs/guides/deployment" }
+      ]
+    }
+  ]
+}
+```
+
+## Tailwind Configuration
+
+Customize colors and styling in `tailwind.config.ts`:
+
+```typescript
+export default {
+  content: ['./src/**/*.{html,js,svelte,ts}'],
+  theme: {
+    extend: {
+      colors: {
+        'primary': '#3b82f6',
+        'secondary': '#8b5cf6'
+      }
+    }
+  }
+};
+```
+
+## Environment Variables
+
+Create a `.env` file in the project root for environment-specific settings:
+
+```bash
+VITE_APP_NAME=My Documentation
+VITE_API_URL=https://api.example.com
+```
+
+Access in your code:
+
+```javascript
+const appName = import.meta.env.VITE_APP_NAME;
+```
+
+## Site Metadata
+
+Customize site metadata in your layout or config:
+
+```svelte
+<svelte:head>
+  <title>My Documentation | Project Name</title>
+  <meta name="description" content="Complete documentation for my project" />
+</svelte:head>
+```
+
+## Advanced Customization
+
+### Custom Components
+
+Create custom Svelte components and import them in your markdown:
+
+```svelte
+<script lang="ts">
+  import CustomComponent from '$lib/CustomComponent.svelte';
+</script>
+
+<CustomComponent prop="value" />
+```
+
+### Custom Styles
+
+Add global styles in `src/app.css`:
+
+```css
+@layer components {
+  .custom-class {
+    @apply px-4 py-2 rounded-lg bg-blue-500 text-white;
+  }
+}
+```
+
+## Performance Tuning
+
+### Image Optimization
+
+Use the Image component for optimized images:
+
+```svelte
+<Image
+  src="/images/screenshot.png"
+  alt="Screenshot"
+  loading="lazy"
+/>
+```
+
+### Code Splitting
+
+Use dynamic imports for large components:
+
+```javascript
+const HeavyComponent = dynamic(() => import('$lib/Heavy.svelte'));
+```
+
+## SEO Configuration
+
+Configure SEO settings:
+
+```json
+{
+  "seo": {
+    "siteName": "My Docs",
+    "description": "Complete documentation",
+    "keywords": ["docs", "guide", "tutorial"],
+    "social": {
+      "twitter": "@myproject",
+      "github": "myorg/mydocs"
+    }
+  }
+}
+```

package/template-starter/docs/guides/github-pages-deployment.md

@@ -0,0 +1,254 @@
+---
+title: Deploy to GitHub Pages
+description: Deploy your documentation site to GitHub Pages
+---
+
+# GitHub Pages Deployment
+
+Deploy your documentation site to GitHub Pages for free hosting directly from your GitHub repository.
+
+## Prerequisites
+
+- GitHub account with repository containing your docs
+- Repository must be public (for free GitHub Pages)
+
+## Step-by-Step Guide
+
+### 1. Enable GitHub Pages
+
+1. Go to your repository settings
+2. Scroll to "GitHub Pages" section
+3. Under "Source", select "GitHub Actions"
+4. Save settings
+
+### 2. Create GitHub Actions Workflow
+
+Create `.github/workflows/deploy.yml`:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: './build'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+```
+
+### 3. Push Workflow File
+
+```bash
+git add .github/workflows/deploy.yml
+git commit -m "Add GitHub Pages deployment workflow"
+git push origin main
+```
+
+### 4. Monitor Deployment
+
+1. Go to "Actions" tab in your repository
+2. Watch the workflow run
+3. Once complete, your site is live at:
+   - `https://yourusername.github.io/repo-name` (for project repo)
+   - `https://yourusername.github.io` (for `yourusername.github.io` repo)
+
+## Configure Base URL
+
+If deploying to a project repository (not your username repo), update `svelte.config.js`:
+
+```javascript
+import adapter from '@sveltejs/adapter-static';
+
+export default {
+  kit: {
+    adapter: adapter({
+      pages: 'build',
+      assets: 'build',
+      fallback: 'index.html'
+    }),
+    prerender: {
+      entries: ['*']
+    },
+    paths: {
+      base: '/repo-name'  // Set this to your repo name
+    }
+  }
+};
+```
+
+Also update links in your docs to use the base path:
+
+```svelte
+<a href={`${base}/docs`}>Docs</a>
+```
+
+## Custom Domain
+
+### Setup Custom Domain on GitHub Pages
+
+1. Go to repository Settings → Pages
+2. Under "Custom domain", enter your domain (e.g., `docs.example.com`)
+3. Click "Save"
+
+### Update DNS Records
+
+Add a `CNAME` record in your domain registrar:
+
+```
+CNAME  docs  yourusername.github.io
+```
+
+Or use an A record pointing to GitHub's IP addresses.
+
+### Enable HTTPS
+
+GitHub Pages automatically provides free HTTPS via Let's Encrypt.
+
+If the domain shows as insecure:
+1. Wait a few minutes for HTTPS to be provisioned
+2. Check "Enforce HTTPS" box in Pages settings
+
+## Automatic Deployments
+
+Every push to the main branch automatically triggers a deployment:
+
+1. Changes are pushed to GitHub
+2. GitHub Actions workflow runs
+3. Build completes and deploys to GitHub Pages
+4. Your site updates automatically
+
+Check the "Actions" tab to monitor deployment progress.
+
+## Rollback Deployments
+
+To rollback to a previous version:
+
+1. Go to "Actions" tab
+2. Find a previous successful workflow run
+3. Click "Re-run jobs"
+4. Workflow redeploys with the previous code
+
+## Troubleshooting
+
+### Workflow Fails
+
+Check the workflow logs:
+1. Go to "Actions" tab
+2. Click on failed workflow
+3. View step details for errors
+
+Common issues:
+- Node version mismatch: Update `node-version` in workflow
+- Missing dependencies: Ensure all packages in `package.json`
+- Build errors: Run `npm run build` locally to test
+
+### Site Not Updating
+
+- Clear browser cache (Ctrl+Shift+Del)
+- Wait a few minutes for DNS propagation
+- Check GitHub Actions workflow completed successfully
+- Verify files in the `build` directory exist
+
+### Custom Domain Not Working
+
+- Verify DNS records are correct
+- Wait 24 hours for DNS propagation
+- Ensure CNAME record points to GitHub Pages
+- Check domain is not redirecting elsewhere
+
+## Performance Tips
+
+### Optimize Build
+
+```yaml
+- name: Build
+  run: npm run build
+  env:
+    VITE_INLINE_BUILD_ASSETS: 'true'
+```
+
+### Enable Caching
+
+The workflow example above includes npm cache:
+```yaml
+- uses: actions/setup-node@v3
+  with:
+    cache: 'npm'
+```
+
+### Minify Assets
+
+Enable minification in `vite.config.ts`:
+```typescript
+build: {
+  minify: 'terser'
+}
+```
+
+## Advanced Configuration
+
+### Deploy on Schedule
+
+Automatically rebuild docs daily:
+
+```yaml
+on:
+  schedule:
+    - cron: '0 0 * * *'  # Daily at midnight
+  push:
+    branches:
+      - main
+```
+
+### Deploy to Multiple Branches
+
+Deploy from different branches to different sites:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - staging
+      - develop
+```
+
+## Limitations
+
+- GitHub Pages serves static files only
+- No serverless functions (use Vercel or Netlify instead)
+- Build time limited to 10 minutes
+- 1 GB soft storage limit
+- 100 GB/month bandwidth limit
+
+## Next Steps
+
+- Set up branch protection to require workflow success
+- Configure automatic PR comments with preview links
+- Set up notifications for deployment failures

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

@@ -0,0 +1,159 @@
+---
+title: Deploy to Netlify
+description: Deploy your documentation site to Netlify
+---
+
+# Netlify Deployment
+
+Deploy your documentation site to Netlify with continuous deployment.
+
+## Prerequisites
+
+- GitHub account and repository with your docs
+- Netlify account (free at https://netlify.com)
+
+## Step-by-Step Guide
+
+### 1. Connect Your Repository
+
+1. Sign in to Netlify at https://app.netlify.com
+2. Click "Add new site"
+3. Select "Import an existing project"
+4. Choose "GitHub" and authorize Netlify
+5. Select your docs repository
+
+### 2. Configure Build Settings
+
+Netlify should auto-detect most settings:
+
+- **Base directory:** (leave empty)
+- **Build command:** `npm run build`
+- **Publish directory:** `build`
+
+### 3. Add Environment Variables
+
+If your site needs environment variables:
+
+1. Go to Site Settings → Environment
+2. Click "Add environment variable"
+3. Add variables like:
+   - `VITE_API_URL=https://api.example.com`
+   - `NODE_ENV=production`
+
+### 4. Deploy
+
+Click "Deploy site" and wait for the build to complete.
+
+Your site will be available at `https://your-site.netlify.app`
+
+## Custom Domain
+
+1. Go to Site Settings → Domain settings
+2. Add your custom domain
+3. Update your domain's DNS settings to point to Netlify
+4. Verify in domain settings
+
+### Free SSL Certificate
+
+Netlify automatically provides a free SSL certificate via Let's Encrypt.
+
+## Continuous Deployment
+
+Every push to your main branch automatically triggers a new deployment:
+
+1. Changes are committed and pushed to GitHub
+2. Netlify webhook triggers a build
+3. Build completes and deploys to production
+4. Your site updates automatically
+
+### Preview Deployments
+
+Push to a feature branch to create a preview deployment:
+- Accessible at `https://branch-name--your-site.netlify.app`
+- Great for testing before merging to main
+
+## Deployment Controls
+
+### Manual Deploy
+
+Redeploy current branch:
+1. Go to "Deploys" tab
+2. Click on a deployment
+3. Click "Publish deploy"
+
+### Rollback
+
+Revert to a previous deployment:
+1. Go to "Deploys" tab
+2. Find the deployment to rollback to
+3. Click "Publish deploy"
+
+## Build Logs
+
+View detailed build logs in "Deploys" tab:
+- Build steps and console output
+- Error messages and warnings
+- Deployment duration
+
+## Monitoring & Analytics
+
+Access site analytics:
+- Go to "Analytics" tab
+- Track page views and user behavior
+- Monitor site performance
+
+## Troubleshooting
+
+### Build Fails
+
+1. Check build logs for errors
+2. Verify build command: `npm run build`
+3. Ensure all dependencies are listed in `package.json`
+4. Run `npm run check` locally to verify types
+
+### Site Returns 404
+
+- Check publish directory is set to `build`
+- Verify files exist in build output
+- Check redirect rules in `netlify.toml`
+
+### Performance Issues
+
+Review performance in Analytics tab:
+- Optimize images and assets
+- Consider using Netlify's image optimization
+- Enable caching strategies
+
+## Advanced Configuration
+
+### Netlify Configuration File
+
+Create `netlify.toml` in your project root:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = "build"
+
+[env]
+  VITE_API_URL = "https://api.example.com"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+### Build Plugins
+
+Enhance your build with Netlify plugins:
+```toml
+[[plugins]]
+  package = "@netlify/plugin-nextjs"
+```
+
+## Next Steps
+
+- Set up form submission handling with Netlify Forms
+- Configure serverless functions if needed
+- Set up automatic backups of your documentation