@alliance-droid/svelte-docs-system 0.0.1

package/docs/en/config/navigation.md

@@ -0,0 +1,505 @@
+---
+title: Navigation Configuration
+description: Configure sidebar, navbar, and breadcrumb navigation
+author: Andrew
+date: 2026-02-05
+---
+
+# Navigation Configuration
+
+Learn how to configure the navigation structure, sidebar sections, and breadcrumbs.
+
+## Navigation Store
+
+The navigation system uses a Svelte store to manage the navigation structure globally. Access it in any component:
+
+```typescript
+import { nav, sidebarOpen } from '$lib/stores/nav';
+```
+
+## Sidebar Navigation
+
+### Basic Configuration
+
+Define your navigation structure in `src/routes/docs/+layout.svelte`:
+
+```svelte
+<script lang="ts">
+  import type { NavSection, NavItem } from '$lib/stores/nav';
+
+  const sections: NavSection[] = [
+    {
+      title: 'Getting Started',
+      items: [
+        { label: 'Home', href: '/docs' },
+        { label: 'Installation', href: '/docs/installation' },
+        { label: 'Quick Start', href: '/docs/quick-start' },
+      ],
+    },
+    {
+      title: 'Components',
+      items: [
+        { label: 'Overview', href: '/docs/components' },
+        { label: 'DocLayout', href: '/docs/components/doclayout' },
+        { label: 'Navbar', href: '/docs/components/navbar' },
+        { label: 'Sidebar', href: '/docs/components/sidebar' },
+        { label: 'Footer', href: '/docs/components/footer' },
+      ],
+    },
+    {
+      title: 'Guides',
+      items: [
+        { label: 'API Integration', href: '/docs/guides/api' },
+        { label: 'Theming', href: '/docs/guides/theming' },
+        { label: 'Deployment', href: '/docs/guides/deployment' },
+      ],
+    },
+  ];
+</script>
+
+<DocLayout {sections} title="Documentation" copyright="© 2026 My Project">
+  <slot />
+</DocLayout>
+```
+
+### Nested Navigation Items
+
+Create multi-level navigation with nested items:
+
+```typescript
+const sections: NavSection[] = [
+  {
+    title: 'Documentation',
+    items: [
+      {
+        label: 'Getting Started',
+        href: '/docs/getting-started',
+        children: [
+          { label: 'Installation', href: '/docs/getting-started/installation' },
+          { label: 'Configuration', href: '/docs/getting-started/config' },
+          { label: 'First Steps', href: '/docs/getting-started/first-steps' },
+        ],
+      },
+      {
+        label: 'API Reference',
+        href: '/docs/api',
+        children: [
+          { label: 'Components', href: '/docs/api/components' },
+          { label: 'Stores', href: '/docs/api/stores' },
+          { label: 'Utilities', href: '/docs/api/utilities' },
+        ],
+      },
+    ],
+  },
+];
+```
+
+### Navigation Item Properties
+
+Each `NavItem` has these properties:
+
+```typescript
+interface NavItem {
+  label: string;              // Display text in sidebar
+  href?: string;              // URL path (optional for parent items)
+  icon?: string;              // FontAwesome icon name (optional)
+  children?: NavItem[];       // Nested items (optional)
+  isActive?: boolean;         // Manually set active state (optional)
+}
+```
+
+Example with icons:
+
+```typescript
+const sections: NavSection[] = [
+  {
+    title: 'Navigation',
+    items: [
+      { label: 'Home', href: '/docs', icon: 'home' },
+      { label: 'Getting Started', href: '/docs/start', icon: 'rocket' },
+      { label: 'API', href: '/docs/api', icon: 'code' },
+      { label: 'Guides', href: '/docs/guides', icon: 'book' },
+    ],
+  },
+];
+```
+
+## Dynamic Navigation
+
+Generate navigation from your documentation structure:
+
+```typescript
+import { readdirSync } from 'fs';
+import { join } from 'path';
+
+function generateNav(): NavSection[] {
+  const docsPath = join(process.cwd(), 'docs/en');
+  
+  // Read directory structure
+  const files = readdirSync(docsPath);
+  
+  const items: NavItem[] = files
+    .filter(f => f.endsWith('.md') && f !== 'index.md')
+    .map(f => {
+      const name = f.replace('.md', '');
+      return {
+        label: name
+          .split('-')
+          .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+          .join(' '),
+        href: `/docs/${name}`,
+      };
+    });
+
+  return [
+    {
+      title: 'Documentation',
+      items: [
+        { label: 'Home', href: '/docs' },
+        ...items,
+      ],
+    },
+  ];
+}
+
+// Use in your layout
+const sections = generateNav();
+```
+
+## Active State Highlighting
+
+The sidebar automatically highlights the current page. To manually control active state:
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/stores';
+
+  let currentPath = $derived($page.url.pathname);
+
+  const sections: NavSection[] = [
+    {
+      title: 'Docs',
+      items: [
+        {
+          label: 'Home',
+          href: '/docs',
+          isActive: currentPath === '/docs',
+        },
+        {
+          label: 'Setup',
+          href: '/docs/setup',
+          isActive: currentPath === '/docs/setup',
+        },
+      ],
+    },
+  ];
+</script>
+```
+
+## Sidebar Configuration
+
+The `Sidebar` component accepts these props:
+
+```typescript
+interface SidebarProps {
+  sections: NavSection[];           // Navigation sections
+  currentPath: string;              // Current route for active highlighting
+  onNavigate?: (path: string) => void; // Called when item clicked
+}
+```
+
+### Mobile Sidebar Behavior
+
+On mobile, the sidebar:
+- Appears as an overlay when toggled
+- Auto-closes after navigation
+- Shows a backdrop overlay
+- Slides in from the left
+
+Configure in `src/lib/components/Sidebar.svelte`:
+
+```svelte
+<script lang="ts">
+  import { sidebarOpen } from '$lib/stores/nav';
+
+  function closeSidebar() {
+    sidebarOpen.set(false);
+  }
+
+  function handleNavigate(path: string) {
+    // Navigate and close on mobile
+    window.location.href = path;
+    if (window.innerWidth < 768) {
+      sidebarOpen.set(false);
+    }
+  }
+</script>
+```
+
+## Navbar Configuration
+
+Configure navbar items in `src/routes/docs/+layout.svelte`:
+
+```svelte
+<script lang="ts">
+  import Navbar from '$lib/components/Navbar.svelte';
+
+  let navbarConfig = {
+    title: 'My Docs',
+    logo: '/logo.svg',
+    onLogoClick: () => window.location.href = '/',
+  };
+</script>
+
+<Navbar {...navbarConfig} />
+```
+
+### Language Selector
+
+Add language switching to navbar (if using i18n):
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/stores';
+
+  let languages = [
+    { code: 'en', label: 'English' },
+    { code: 'es', label: 'Español' },
+    { code: 'fr', label: 'Français' },
+  ];
+
+  function switchLanguage(lang: string) {
+    const currentPath = $page.url.pathname.replace('/docs', '');
+    window.location.href = `/docs/${lang}${currentPath}`;
+  }
+</script>
+```
+
+### Version Selector
+
+Add version switching (for multi-version docs):
+
+```svelte
+<script lang="ts">
+  let versions = [
+    { number: '2.0', label: 'Latest' },
+    { number: '1.5', label: '1.5 (LTS)' },
+    { number: '1.0', label: '1.0 (Archived)' },
+  ];
+
+  function switchVersion(version: string) {
+    window.location.href = `/docs/${version}/`;
+  }
+</script>
+```
+
+## Breadcrumbs
+
+The `Breadcrumbs` component displays the current page path:
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs from '$lib/components/Breadcrumbs.svelte';
+
+  let items = [
+    { label: 'Home', href: '/' },
+    { label: 'Docs', href: '/docs' },
+    { label: 'Getting Started', href: '/docs/getting-started' },
+    { label: 'Installation' }, // Current page (no href)
+  ];
+</script>
+
+<Breadcrumbs {items} />
+```
+
+### Auto-Generate Breadcrumbs from Current Path
+
+```typescript
+function generateBreadcrumbs(pathname: string) {
+  const segments = pathname
+    .split('/')
+    .filter(s => s && s !== 'docs');
+
+  const items = [
+    { label: 'Docs', href: '/docs' },
+    ...segments.map((segment, index) => {
+      const href = '/docs/' + segments.slice(0, index + 1).join('/');
+      const label = segment
+        .split('-')
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+
+      return {
+        label,
+        href: index === segments.length - 1 ? undefined : href,
+      };
+    }),
+  ];
+
+  return items;
+}
+```
+
+## Section Collapsing
+
+Make sidebar sections collapsible:
+
+```svelte
+<script lang="ts">
+  let expandedSections: Set<string> = new Set();
+
+  function toggleSection(title: string) {
+    if (expandedSections.has(title)) {
+      expandedSections.delete(title);
+    } else {
+      expandedSections.add(title);
+    }
+    expandedSections = expandedSections;
+  }
+
+  const sections: NavSection[] = [
+    { title: 'Getting Started', items: [...] },
+    { title: 'Components', items: [...] },
+  ];
+</script>
+
+{#each sections as section (section.title)}
+  <div class="section">
+    <button on:click={() => toggleSection(section.title)}>
+      {section.title}
+      <span class:rotated={expandedSections.has(section.title)}>
+        ▼
+      </span>
+    </button>
+
+    {#if expandedSections.has(section.title)}
+      <nav>
+        {#each section.items as item (item.label)}
+          <a href={item.href} class:active={item.isActive}>
+            {item.label}
+          </a>
+        {/each}
+      </nav>
+    {/if}
+  </div>
+{/each}
+
+<style>
+  .rotated {
+    transform: rotate(180deg);
+  }
+</style>
+```
+
+## Search Navigation
+
+Integrate Pagefind search with navigation:
+
+```svelte
+<script lang="ts">
+  import Search from '$lib/components/Search.svelte';
+  import { sidebarOpen } from '$lib/stores/nav';
+
+  function handleSearch(result: SearchResult) {
+    window.location.href = result.url;
+    sidebarOpen.set(false);
+  }
+</script>
+
+<div class="navbar">
+  <Search onSelect={handleSearch} />
+</div>
+```
+
+## Configuration Types
+
+```typescript
+// Navigation types
+interface NavSection {
+  title: string;
+  items: NavItem[];
+}
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+  isActive?: boolean;
+}
+
+// Store types
+interface NavStoreData {
+  sections: NavSection[];
+  title?: string;
+  logo?: string | null;
+  copyright?: string;
+  footerLinks?: { label: string; href: string }[];
+}
+```
+
+## Best Practices
+
+1. **Group related items:** Use sections to organize navigation logically
+2. **Limit depth:** Keep nesting to 2-3 levels maximum
+3. **Use consistent labels:** Make labels clear and concise
+4. **Add icons:** Use FontAwesome icons for visual clarity
+5. **Test on mobile:** Ensure sidebar is usable on small screens
+6. **Link to first child:** Parent items with `href` pointing to overview
+7. **Update dynamically:** Load navigation from a config file or database
+
+## Example: Complex Navigation
+
+```typescript
+const sections: NavSection[] = [
+  {
+    title: 'Get Started',
+    items: [
+      { label: 'Welcome', href: '/docs', icon: 'home' },
+      { label: 'Installation', href: '/docs/install', icon: 'download' },
+      { label: 'Quick Start', href: '/docs/quick-start', icon: 'rocket' },
+    ],
+  },
+  {
+    title: 'Learn',
+    items: [
+      {
+        label: 'Core Concepts',
+        href: '/docs/concepts',
+        icon: 'lightbulb',
+        children: [
+          { label: 'Architecture', href: '/docs/concepts/architecture' },
+          { label: 'Components', href: '/docs/concepts/components' },
+          { label: 'Stores', href: '/docs/concepts/stores' },
+        ],
+      },
+      {
+        label: 'Guides',
+        href: '/docs/guides',
+        icon: 'book',
+        children: [
+          { label: 'API Integration', href: '/docs/guides/api' },
+          { label: 'Authentication', href: '/docs/guides/auth' },
+          { label: 'Deployment', href: '/docs/guides/deploy' },
+        ],
+      },
+    ],
+  },
+  {
+    title: 'Reference',
+    items: [
+      { label: 'API Docs', href: '/docs/api', icon: 'code' },
+      { label: 'Components', href: '/docs/components', icon: 'puzzle' },
+      { label: 'CLI', href: '/docs/cli', icon: 'terminal' },
+    ],
+  },
+  {
+    title: 'Support',
+    items: [
+      { label: 'FAQ', href: '/docs/faq', icon: 'circle-question' },
+      { label: 'Troubleshooting', href: '/docs/troubleshooting', icon: 'wrench' },
+      { label: 'Contributing', href: '/docs/contributing', icon: 'git' },
+    ],
+  },
+];
+```