@alliance-droid/svelte-docs-system 0.0.1

package/docs/en/troubleshooting.md

@@ -0,0 +1,704 @@
+---
+title: Troubleshooting Guide
+description: Solutions for common issues and problems
+author: Andrew
+date: 2026-02-05
+---
+
+# Troubleshooting Guide
+
+Solutions for common problems when using the SvelteKit Documentation System.
+
+## Build & Development Issues
+
+### Problem: `npm run dev` fails with module errors
+
+**Error Message:**
+```
+Error: Cannot find module '@sveltejs/kit'
+Module not found
+```
+
+**Solution:**
+1. Ensure all dependencies are installed:
+   ```bash
+   npm install
+   ```
+
+2. Clear the `.svelte-kit` build cache:
+   ```bash
+   rm -rf .svelte-kit
+   npm run dev
+   ```
+
+3. If issue persists, reinstall node_modules:
+   ```bash
+   rm -rf node_modules
+   npm install
+   npm run dev
+   ```
+
+**Prevention:**
+- Run `npm install` after pulling new changes
+- Commit `package-lock.json` to version control
+
+---
+
+### Problem: TypeScript compilation errors
+
+**Error Message:**
+```
+src/lib/components/DocLayout.svelte:12 error
+Type '...' is not assignable to type 'unknown'
+```
+
+**Solution:**
+1. Check your `tsconfig.json` is correct:
+   ```json
+   {
+     "compilerOptions": {
+       "strict": true,
+       "target": "ES2020",
+       "module": "ESNext"
+     }
+   }
+   ```
+
+2. Rebuild TypeScript cache:
+   ```bash
+   npm run check
+   ```
+
+3. Review the specific error - ensure props match component interface
+
+**Prevention:**
+- Run `npm run check` before commits
+- Enable TypeScript strict mode in your IDE
+
+---
+
+### Problem: Tailwind CSS not compiling
+
+**Symptoms:**
+- Page appears completely unstyled
+- No colors or spacing applied
+- Classes like `text-blue-500` don't work
+
+**Solution:**
+1. Verify `tailwind.config.ts` exists and is correct:
+   ```bash
+   cat tailwind.config.ts
+   ```
+
+2. Check `src/app.css` includes Tailwind directives:
+   ```css
+   @tailwind base;
+   @tailwind components;
+   @tailwind utilities;
+   ```
+
+3. Ensure Tailwind is installed:
+   ```bash
+   npm install -D tailwindcss postcss autoprefixer
+   ```
+
+4. Check `postcss.config.js`:
+   ```js
+   export default {
+     plugins: {
+       tailwindcss: {},
+       autoprefixer: {},
+     },
+   };
+   ```
+
+5. Restart dev server:
+   ```bash
+   npm run dev
+   ```
+
+**Prevention:**
+- Run `npm run check` to verify CSS compilation
+- Don't manually edit compiled CSS files
+
+---
+
+## Routing & Navigation Issues
+
+### Problem: Documentation pages return 404
+
+**Symptoms:**
+- Clicking sidebar links shows "Not Found"
+- URL bar shows `/docs/setup` but page doesn't load
+- Even `http://localhost:5173/docs` shows 404
+
+**Solution:**
+1. Verify route files exist:
+   ```bash
+   ls -la src/routes/docs/
+   # Should show: +layout.svelte, [...slug]/, etc.
+   ```
+
+2. Check markdown files exist:
+   ```bash
+   ls -la docs/
+   # Should show: index.md, setup.md, etc.
+   ```
+
+3. Verify `[...slug]/+page.svelte` fetches from correct path:
+   ```svelte
+   const path = `/docs/${slug}.md`;  // ← Correct
+   // NOT: const path = `docs/${slug}.md`;  // ← Wrong
+   ```
+
+4. Check file names don't have spaces (use hyphens):
+   ```bash
+   # Correct:
+   setup.md
+   getting-started.md
+   
+   # Incorrect:
+   Setup Guide.md
+   ```
+
+5. Clear SvelteKit build cache and rebuild:
+   ```bash
+   rm -rf .svelte-kit
+   npm run dev
+   ```
+
+**Prevention:**
+- Use consistent naming: lowercase with hyphens
+- Keep documentation files in `docs/` folder
+- Test route handlers by visiting `/docs` directly
+
+---
+
+### Problem: Sidebar doesn't show navigation items
+
+**Symptoms:**
+- Sidebar appears but no items are listed
+- "Getting Started" section shows but no links underneath
+- Navigation is completely empty
+
+**Solution:**
+1. Verify `sections` array is defined in `+layout.svelte`:
+   ```svelte
+   const sections: NavSection[] = [
+     {
+       title: 'Getting Started',
+       items: [
+         { label: 'Home', href: '/docs' },
+       ],
+     },
+   ];
+   ```
+
+2. Check `sections` is passed to `DocLayout`:
+   ```svelte
+   <DocLayout {sections} title="Docs">
+     <slot />
+   </DocLayout>
+   ```
+
+3. Verify href paths start with correct mount point:
+   ```typescript
+   // Correct:
+   { label: 'Home', href: '/docs' }
+   
+   // Incorrect:
+   { label: 'Home', href: '/help' }  // Wrong mount point
+   { label: 'Home', href: 'docs' }   // Missing leading slash
+   ```
+
+4. Ensure `NavSection` and `NavItem` types match:
+   ```typescript
+   interface NavSection {
+     title: string;
+     items: NavItem[];
+   }
+   
+   interface NavItem {
+     label: string;
+     href?: string;
+   }
+   ```
+
+**Prevention:**
+- Test navigation in browser dev tools
+- Log `sections` to console to verify structure
+- Use TypeScript strict mode to catch type errors
+
+---
+
+### Problem: Sidebar is hidden or not responsive on mobile
+
+**Symptoms:**
+- Sidebar doesn't appear on mobile devices
+- Hamburger menu doesn't toggle sidebar
+- Sidebar doesn't close after clicking links on mobile
+
+**Solution:**
+1. Check hamburger button is in navbar:
+   ```svelte
+   <!-- Should be in Navbar.svelte -->
+   <button class="md:hidden" on:click={() => sidebarOpen.toggle()}>
+     <i class="fa-solid fa-bars"></i>
+   </button>
+   ```
+
+2. Verify `sidebarOpen` store is imported:
+   ```typescript
+   import { sidebarOpen } from '$lib/stores/nav';
+   ```
+
+3. Check media query in styles:
+   ```svelte
+   <!-- Sidebar should hide on mobile -->
+   <aside class="hidden md:block">
+   ```
+
+4. Test in browser dev tools:
+   - Open DevTools (F12)
+   - Go to Device Toolbar (Ctrl+Shift+M)
+   - Change viewport size
+   - Verify sidebar behavior
+
+**Prevention:**
+- Test responsive design regularly
+- Use browser dev tools mobile emulation
+- Test on actual mobile devices before deployment
+
+---
+
+## Styling & Theme Issues
+
+### Problem: Dark mode doesn't work
+
+**Symptoms:**
+- Toggle button exists but clicking does nothing
+- Theme doesn't persist on page reload
+- Page doesn't respect system dark mode preference
+
+**Solution:**
+1. Verify theme store is initialized in main layout:
+   ```svelte
+   <!-- src/routes/+layout.svelte -->
+   <script lang="ts">
+     import { theme } from '$lib/stores/theme';
+     import { onMount } from 'svelte';
+
+     onMount(() => {
+       // Initialize theme from localStorage
+       const stored = localStorage.getItem('theme') || 'system';
+       theme.set(stored as any);
+     });
+   </script>
+   ```
+
+2. Check dark colors are defined in `tailwind.config.ts`:
+   ```typescript
+   colors: {
+     'claude-dark-bg': '#1A1A1A',
+     'claude-dark-text': '#FFFFFF',
+     // ... etc
+   }
+   ```
+
+3. Verify `darkMode: 'class'` is set:
+   ```typescript
+   export default {
+     darkMode: 'class',
+     // ...
+   } satisfies Config;
+   ```
+
+4. Test theme store directly in browser console:
+   ```javascript
+   // Open DevTools console
+   localStorage.setItem('theme', 'dark');
+   window.location.reload();
+   // Should switch to dark mode
+   ```
+
+5. Check HTML root element has `dark` class:
+   ```html
+   <!-- DevTools > Elements > <html> -->
+   <!-- Should have: class="dark" when dark mode is enabled -->
+   ```
+
+**Prevention:**
+- Test dark mode toggle frequently
+- Test theme persistence across page reloads
+- Verify contrast ratios in both themes
+
+---
+
+### Problem: Custom colors aren't applied
+
+**Symptoms:**
+- Changed `tailwind.config.ts` but colors don't update
+- Custom background color shows as default
+- Sidebar doesn't use your brand colors
+
+**Solution:**
+1. Verify config changes are correct:
+   ```typescript
+   export default {
+     theme: {
+       extend: {
+         colors: {
+           'claude-bg': '#YOUR_COLOR',
+         },
+       },
+     },
+   } satisfies Config;
+   ```
+
+2. Use correct color names in components:
+   ```svelte
+   <!-- Correct: -->
+   <div class="bg-claude-bg">Content</div>
+   
+   <!-- Incorrect: -->
+   <div class="bg-white">Content</div>  <!-- Uses default Tailwind -->
+   ```
+
+3. Restart dev server:
+   ```bash
+   npm run dev
+   ```
+
+4. Clear browser cache:
+   - Ctrl+Shift+Delete (or Cmd+Shift+Delete on Mac)
+   - Select "Cached images and files"
+   - Clear
+
+5. Check CSS is being generated:
+   ```bash
+   # Look for generated CSS in output
+   npm run build
+   # Check build/ directory for CSS files
+   ```
+
+**Prevention:**
+- Use consistent color naming
+- Document your color palette
+- Test color changes immediately
+- Use browser dev tools to inspect applied styles
+
+---
+
+### Problem: Icons from FontAwesome don't appear
+
+**Symptoms:**
+- Icon elements show empty squares or broken images
+- FontAwesome classes render as text instead of icons
+- Icons appear in some places but not others
+
+**Solution:**
+1. Verify FontAwesome is installed:
+   ```bash
+   npm list @fortawesome/fontawesome-free
+   # Should show installed version
+   ```
+
+2. Check FontAwesome CSS is imported in `src/app.css`:
+   ```css
+   @import '@fortawesome/fontawesome-free/css/all.css';
+   ```
+
+3. Verify icon classes are correct format:
+   ```svelte
+   <!-- Correct formats: -->
+   <i class="fa-solid fa-home"></i>
+   <i class="fa-regular fa-user"></i>
+   <i class="fa-brands fa-github"></i>
+   
+   <!-- Incorrect: -->
+   <i class="fa-home"></i>  <!-- Missing weight class -->
+   <i class="home"></i>     <!-- Not FontAwesome -->
+   ```
+
+4. Check icon exists in free version:
+   ```bash
+   # Some icons require pro version
+   # Use free alternatives: https://fontawesome.com/icons
+   ```
+
+5. Build and verify:
+   ```bash
+   npm run build
+   # Check if CSS includes FontAwesome styles
+   ```
+
+**Prevention:**
+- Use official FontAwesome icon list
+- Test new icons immediately
+- Use consistent icon naming (fa-solid, fa-regular, etc.)
+
+---
+
+## Performance Issues
+
+### Problem: Documentation site is slow to load
+
+**Symptoms:**
+- First load takes more than 3 seconds
+- Page transitions are laggy
+- Build takes over 30 seconds
+
+**Solution:**
+1. Check build time:
+   ```bash
+   time npm run build
+   # Should complete in under 30 seconds
+   ```
+
+2. Identify slow components:
+   ```bash
+   npm run build -- --verbose
+   # Look for files taking longest to build
+   ```
+
+3. Optimize Tailwind CSS:
+   ```typescript
+   // tailwind.config.ts - Limit which files to scan
+   export default {
+     content: ['./src/**/*.{html,js,svelte,ts}'],
+     // DON'T include: ./docs/**/* (not needed at build time)
+   };
+   ```
+
+4. Use dynamic imports for heavy components:
+   ```svelte
+   <script lang="ts">
+     import { browser } from '$app/environment';
+     let HeavyComponent: any;
+     
+     if (browser) {
+       import('./HeavyComponent.svelte').then(m => {
+         HeavyComponent = m.default;
+       });
+     }
+   </script>
+   ```
+
+5. Check for large images in docs:
+   ```bash
+   find docs -type f -name "*.png" -o -name "*.jpg"
+   # Optimize images if over 100KB
+   ```
+
+6. Enable caching in production:
+   ```typescript
+   // svelte.config.js
+   export default {
+     kit: {
+       cacheControl: {
+         maxage: 60 * 60 * 24 * 365,
+       },
+     },
+   };
+   ```
+
+**Prevention:**
+- Monitor build times regularly
+- Optimize images before adding
+- Use lazy loading for images
+- Minimize external dependencies
+
+---
+
+### Problem: Search is slow or doesn't find results
+
+**Symptoms:**
+- Search takes more than 1 second to respond
+- Searching doesn't return expected results
+- Search index seems out of date
+
+**Solution:**
+1. Rebuild search index:
+   ```bash
+   npm run build
+   # This regenerates Pagefind index
+   ```
+
+2. Check Pagefind configuration:
+   ```toml
+   # pagefind.toml
+   [build]
+   source = "build"  # Correct directory
+   output_subdir = "_pagefind"
+   
+   [index]
+   relative_urls = true
+   ```
+
+3. Verify search files are generated:
+   ```bash
+   ls -la build/_pagefind/
+   # Should show: chunk.html, index.html, etc.
+   ```
+
+4. Check if pages are indexed:
+   ```bash
+   # Look for index summary during build
+   npm run build 2>&1 | grep -i "pages indexed"
+   ```
+
+5. Clear and rebuild:
+   ```bash
+   rm -rf build
+   npm run build
+   ```
+
+**Prevention:**
+- Run `npm run build` before deploying
+- Test search functionality after adding docs
+- Monitor search performance in production
+
+---
+
+## Deployment Issues
+
+### Problem: Documentation not accessible after deployment
+
+**Symptoms:**
+- Works locally with `npm run dev`
+- Fails after deploying to Vercel, Netlify, etc.
+- 404 errors in production
+
+**Solution:**
+1. Verify build succeeds:
+   ```bash
+   npm run build
+   npm run preview
+   # Should work like production
+   ```
+
+2. Check adapter is configured for your deployment:
+   ```typescript
+   // svelte.config.js - for static sites
+   import adapter from '@sveltejs/adapter-static';
+   
+   export default {
+     kit: {
+       adapter: adapter({
+         pages: 'build',
+         assets: 'build',
+         fallback: 'index.html',
+         precompress: false,
+       }),
+     },
+   };
+   ```
+
+3. For Vercel:
+   ```bash
+   vercel --prod
+   # Check logs: vercel logs --follow
+   ```
+
+4. For Netlify:
+   ```bash
+   netlify deploy --prod --dir=build
+   # Check: netlify status
+   ```
+
+5. Verify environment variables:
+   ```bash
+   # Deployment platform should have no special env vars needed
+   # If errors, check platform logs
+   ```
+
+6. Check deployment logs for errors:
+   - Vercel: https://vercel.com/dashboard
+   - Netlify: https://app.netlify.com
+   - GitHub Pages: Actions tab
+
+**Prevention:**
+- Test production build locally first
+- Use `npm run preview` to verify
+- Keep adapter configuration in version control
+- Test deployment on staging environment
+
+---
+
+## Common Errors & Solutions
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| **Module not found** | Missing node_modules | Run `npm install` |
+| **ENOENT: no such file** | File/folder doesn't exist | Create missing file/folder |
+| **Port 5173 in use** | Another process using port | Change port: `npm run dev -- --port 3000` |
+| **CSS not loading** | Tailwind not compiled | Run `npm run dev` from project root |
+| **Routes not found** | File structure incorrect | Ensure `src/routes/docs/` exists |
+| **Props error** | Component props mismatch | Check TypeScript types |
+| **Dark mode not persisting** | localStorage not working | Ensure `theme` store initializes |
+| **Images not loading** | Wrong path or 404 | Use absolute paths: `/images/name.png` |
+| **Search not working** | Index not generated | Run `npm run build` |
+| **Sidebar not responsive** | CSS not applied | Clear cache and restart dev server |
+
+---
+
+## Getting More Help
+
+If you can't find the solution:
+
+1. **Check the logs:**
+   ```bash
+   # See detailed error messages
+   npm run dev -- --verbose
+   npm run build -- --verbose
+   ```
+
+2. **Check browser console:**
+   - Open DevTools (F12)
+   - Go to Console tab
+   - Look for red error messages
+
+3. **Check browser Network tab:**
+   - Open DevTools (F12)
+   - Go to Network tab
+   - Look for failed requests (red)
+
+4. **Common debugging:**
+   ```javascript
+   // In browser console:
+   console.log(localStorage.getItem('theme'));  // Check theme
+   console.log(document.documentElement.className);  // Check classes
+   ```
+
+5. **Create minimal reproduction:**
+   - Remove custom code
+   - Test with default setup
+   - Add features one by one
+
+6. **Check documentation:**
+   - [SvelteKit Docs](https://kit.svelte.dev)
+   - [Svelte 5 Docs](https://svelte.dev)
+   - [Tailwind CSS Docs](https://tailwindcss.com)
+
+---
+
+## Still Stuck?
+
+If none of these solutions work:
+
+1. **Document the issue:**
+   - What you were trying to do
+   - Exact error message(s)
+   - Steps to reproduce
+   - Your environment (Node version, OS, etc.)
+
+2. **Check GitHub issues:**
+   - Search existing issues
+   - Create new issue with details
+
+3. **Ask in community:**
+   - Svelte Discord: https://discord.gg/svelte
+   - SvelteKit Discussions: GitHub Discussions
+   - Stack Overflow with `svelte` tag
+
+Good luck! 🚀