@alliance-droid/svelte-docs-system 0.0.1

package/docs/de/index.md

@@ -0,0 +1,41 @@
+---
+title: Dokumentationsstartseite
+description: Willkommen beim SvelteKit-Dokumentationssystem
+author: Andrew
+date: 2026-02-05
+---
+
+# Willkommen beim Dokumentationssystem
+
+Dies ist die Startseite Ihrer Dokumentationswebsite. Sie demonstriert das Markdown-Routingsystem in Aktion.
+
+## Funktionen
+
+- **Automatisches Routing** von Markdown-Dateien
+- **Unterstützung verschachtelter Pfade** (Dokumente in Ordnern organisieren)
+- **Frontmatter-Metadaten** (Titel, Autor, Datum)
+- **Professionelle Formatierung** sofort einsatzbereit
+- **Einfach zu personalisieren** und zu erweitern
+
+## Erste Schritte
+
+Schauen Sie sich die [Installationsanleitung](/docs/de/setup) an, um zu beginnen.
+
+## Projektstruktur
+
+```
+docs/
+├── index.md                 (Diese Datei)
+├── setup.md                (Erste-Schritte-Anleitung)
+├── routing.md              (Funktionsweise des Routings)
+├── api/
+│   ├── overview.md         (API-Übersicht)
+│   └── examples.md         (API-Beispiele)
+└── guides/
+    └── advanced.md         (Fortgeschrittene Themen)
+```
+
+Jede Markdown-Datei wird automatisch zu einer Route:
+- `docs/setup.md` → `/docs/de/setup`
+- `docs/api/overview.md` → `/docs/de/api/overview`
+- `docs/guides/advanced.md` → `/docs/de/guides/advanced`

package/docs/en/COMPONENTS.md

@@ -0,0 +1,443 @@
+# Core Documentation Components
+
+A collection of reusable Svelte 5 components for building beautiful, accessible documentation sites.
+
+---
+
+## Table of Contents
+
+1. [Callout](#callout) - Alert boxes with variants
+2. [Tabs](#tabs) - Switchable content panels
+3. [CodeBlock](#codeblock) - Code display with copy button
+4. [Image](#image) - Responsive images with captions
+5. [APITable](#apitable) - API reference tables
+6. [Breadcrumbs](#breadcrumbs) - Navigation breadcrumbs
+
+---
+
+## Callout
+
+**Component:** `<Callout />`
+
+Alert/notification boxes for highlighting important information.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'info' \| 'warning' \| 'success' \| 'error'` | `'info'` | Visual style variant |
+| `title` | `string` | `undefined` | Optional callout title |
+| `children` | `Snippet` | required | Content to display |
+
+### Variants
+
+- **info** (blue) - General information and tips
+- **warning** (amber) - Caution messages
+- **success** (green) - Positive/successful messages
+- **error** (red) - Error or critical messages
+
+### Usage Examples
+
+```svelte
+<Callout variant="info" title="Note">
+  This is informational content.
+</Callout>
+
+<Callout variant="warning" title="Warning">
+  Be careful with this setting.
+</Callout>
+
+<Callout variant="success" title="Success">
+  Operation completed successfully!
+</Callout>
+
+<Callout variant="error" title="Error">
+  Something went wrong. Please try again.
+</Callout>
+```
+
+### Styling
+
+- Default background and border colors based on variant
+- Dark mode support with `dark:` classes
+- Font Awesome icons for visual indicators
+- Responsive padding and layout
+
+---
+
+## Tabs
+
+**Component:** `<Tabs />`
+
+Display multiple content panels with tab navigation.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `TabItem[]` | required | Array of tab definitions |
+| `defaultIndex` | `number` | `0` | Initially active tab index |
+
+### TabItem Type
+
+```typescript
+interface TabItem {
+  label: string;        // Tab button label
+  content?: string;     // HTML content (optional)
+}
+```
+
+### Usage Examples
+
+```svelte
+<script>
+  const tabs = [
+    { label: 'JavaScript', content: '<code>const x = 42;</code>' },
+    { label: 'Python', content: '<code>x = 42</code>' },
+    { label: 'Rust', content: '<code>let x = 42;</code>' }
+  ];
+</script>
+
+<Tabs items={tabs} defaultIndex={0} />
+```
+
+### Features
+
+- Click to switch between tabs
+- Active tab highlighting
+- HTML content rendering
+- Smooth transitions
+- Keyboard accessible
+
+---
+
+## CodeBlock
+
+**Component:** `<CodeBlock />`
+
+Display code with syntax highlighting and copy functionality.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `code` | `string` | required | The code content to display |
+| `language` | `string` | `'plaintext'` | Programming language identifier |
+| `filename` | `string` | `undefined` | Optional filename header |
+
+### Usage Examples
+
+```svelte
+<CodeBlock
+  code="console.log('Hello, World!');"
+  language="javascript"
+  filename="hello.js"
+/>
+
+<CodeBlock
+  code={`function greet(name) {
+  return \`Hello, \${name}!\`;
+}`}
+  language="javascript"
+  filename="greet.js"
+/>
+
+<CodeBlock
+  code="npm install @mypackage/docs"
+  language="bash"
+/>
+```
+
+### Features
+
+- Copy-to-clipboard button
+- Language label display
+- Optional filename header
+- Monospace font rendering
+- Dark mode support
+- Visual feedback on copy
+
+---
+
+## Image
+
+**Component:** `<Image />`
+
+Responsive images with caption and zoom functionality.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Image source URL |
+| `alt` | `string` | required | Alt text for accessibility |
+| `caption` | `string` | `undefined` | Optional image caption |
+| `width` | `number` | `undefined` | Image width (optional) |
+| `height` | `number` | `undefined` | Image height (optional) |
+| `zoomable` | `boolean` | `true` | Enable zoom on click |
+
+### Usage Examples
+
+```svelte
+<Image
+  src="/path/to/image.jpg"
+  alt="A beautiful landscape"
+  caption="Sunset over the mountains"
+/>
+
+<Image
+  src="https://via.placeholder.com/600x400"
+  alt="Placeholder"
+  caption="This image can be zoomed"
+  width={600}
+  height={400}
+  zoomable={true}
+/>
+
+<Image
+  src="/screenshot.png"
+  alt="App screenshot"
+  zoomable={false}
+/>
+```
+
+### Features
+
+- Responsive layout
+- Click to zoom overlay
+- Figure caption support
+- Keyboard support (ESC to close)
+- Accessible markup
+- Image dimensions support
+
+---
+
+## APITable
+
+**Component:** `<APITable />`
+
+Display API reference documentation in table format.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `Column[]` | required | Column definitions |
+| `rows` | `Row[]` | required | Table data rows |
+| `title` | `string` | `undefined` | Optional table title |
+| `description` | `string` | `undefined` | Optional description |
+
+### Column Type
+
+```typescript
+interface Column {
+  key: string;        // Data key
+  label: string;      // Column header label
+  width?: string;     // Optional CSS width
+}
+```
+
+### Usage Examples
+
+```svelte
+<script>
+  const columns = [
+    { key: 'name', label: 'Parameter Name' },
+    { key: 'type', label: 'Type' },
+    { key: 'required', label: 'Required' },
+    { key: 'description', label: 'Description', width: '40%' }
+  ];
+
+  const rows = [
+    {
+      name: 'apiKey',
+      type: 'string',
+      required: true,
+      description: 'Your API authentication key'
+    },
+    {
+      name: 'timeout',
+      type: 'number',
+      required: false,
+      description: 'Request timeout in milliseconds'
+    }
+  ];
+</script>
+
+<APITable
+  title="API Configuration"
+  description="Configuration options for the API client"
+  columns={columns}
+  rows={rows}
+/>
+```
+
+### Features
+
+- Sortable column layout
+- Alternate row colors
+- Boolean/null value formatting
+- Custom column widths
+- Title and description support
+- Empty state handling
+- Dark mode styling
+
+---
+
+## Breadcrumbs
+
+**Component:** `<Breadcrumbs />`
+
+Navigation breadcrumb trail showing current page location.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `BreadcrumbItem[]` | required | Breadcrumb items |
+
+### BreadcrumbItem Type
+
+```typescript
+interface BreadcrumbItem {
+  label: string;       // Display text
+  href?: string;       // Optional link URL
+}
+```
+
+### Usage Examples
+
+```svelte
+<script>
+  const breadcrumbs = [
+    { label: 'Home', href: '/' },
+    { label: 'Docs', href: '/docs' },
+    { label: 'Components', href: '/docs/components' },
+    { label: 'Callout' }  // Current page (no href)
+  ];
+</script>
+
+<Breadcrumbs items={breadcrumbs} />
+```
+
+### Features
+
+- Clickable navigation links
+- Chevron separators
+- Current page indicator
+- Semantic HTML (`<nav>`, `<ol>`, `<li>`)
+- Keyboard accessible
+- Dark mode support
+- Responsive layout
+
+---
+
+## Dark Mode Support
+
+All components include built-in dark mode support using Tailwind CSS `dark:` variants.
+
+To enable dark mode:
+
+```svelte
+<script>
+  import { theme } from '$lib/stores/theme';
+</script>
+
+<button onclick={() => theme.toggle()}>
+  Toggle Dark Mode
+</button>
+```
+
+---
+
+## Accessibility
+
+All components are built with accessibility in mind:
+
+- Semantic HTML structure
+- ARIA labels and roles
+- Keyboard navigation
+- Focus management
+- Color contrast compliance
+- Alt text support
+
+---
+
+## Installation & Export
+
+All components are exported from `$lib`:
+
+```svelte
+<script>
+  import { 
+    Callout, 
+    Tabs, 
+    CodeBlock, 
+    Image, 
+    APITable, 
+    Breadcrumbs 
+  } from '$lib';
+</script>
+```
+
+---
+
+## Testing
+
+Component tests are provided in `src/lib/components/*.test.ts`:
+
+```bash
+npm test                 # Run all tests
+npm run test:coverage    # Generate coverage report
+```
+
+---
+
+## Styling with Tailwind
+
+Components use Tailwind CSS for styling. Customize by editing `tailwind.config.js`:
+
+```javascript
+export default {
+  content: ['./src/**/*.{html,js,svelte,ts}'],
+  theme: {
+    extend: {
+      colors: {
+        'doc-info': '#0ea5e9',
+        'doc-warning': '#f59e0b',
+        'doc-success': '#10b981',
+        'doc-error': '#ef4444',
+      },
+    },
+  },
+};
+```
+
+---
+
+## Performance Notes
+
+- Components are lightweight and performant
+- No external dependencies required
+- SSR compatible
+- Optimized bundle size
+- Lazy loading compatible
+
+---
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Svelte 5+
+- JavaScript required (but graceful degradation)
+
+---
+
+## License
+
+MIT - Free for personal and commercial use
+
+---
+
+**Last Updated:** February 4, 2026
+**Version:** 1.0.0

package/docs/en/api/examples.md

@@ -0,0 +1,100 @@
+---
+title: API Examples
+description: Code examples for using the documentation system
+author: Andrew
+date: 2026-02-05
+---
+
+# API Examples
+
+Here are practical examples of using the documentation system.
+
+## Loading a Document
+
+```typescript
+import { loadMarkdownBySlug } from '$lib/markdown';
+
+const doc = await loadMarkdownBySlug('./docs', 'setup');
+
+console.log(doc.title);        // "Setup Guide"
+console.log(doc.slug);         // "setup"
+console.log(doc.html);         // <h1>Setup Guide</h1>...
+console.log(doc.metadata);     // { title, author, date }
+```
+
+## Scanning All Documents
+
+```typescript
+import { scanDocsFolder, getSlugs } from '$lib/scanner';
+
+const structure = await scanDocsFolder('./docs');
+const slugs = getSlugs(structure);
+
+slugs.forEach(slug => {
+  console.log(`Found: ${slug}`);
+});
+// Output:
+// Found: index
+// Found: setup
+// Found: routing
+// Found: api/overview
+// Found: api/examples
+```
+
+## Building Navigation
+
+```typescript
+import { scanDocsFolder, buildNavStructure } from '$lib/scanner';
+
+const structure = await scanDocsFolder('./docs');
+const nav = buildNavStructure(structure);
+
+// nav contains hierarchical structure for building sidebar
+console.log(nav);
+```
+
+## In a SvelteKit Route
+
+```typescript
+// src/routes/docs/[...slug]/+page.ts
+import { loadMarkdownBySlug } from '$lib/markdown';
+import { error } from '@sveltejs/kit';
+
+export async function load({ params }) {
+  const slug = params.slug || 'index';
+  const doc = await loadMarkdownBySlug('./docs', slug);
+  
+  if (!doc) {
+    throw error(404, 'Page not found');
+  }
+  
+  return { doc };
+}
+```
+
+## Extracting Metadata
+
+```typescript
+import { extractMetadata } from '$lib/markdown';
+
+const meta = await extractMetadata('./docs/setup.md');
+console.log(meta);
+// { title: 'Setup Guide', author: 'Andrew', date: '2026-02-05' }
+```
+
+## Generating Table of Contents
+
+```typescript
+import { loadMarkdownBySlug, generateTableOfContents } from '$lib/markdown';
+
+const doc = await loadMarkdownBySlug('./docs', 'setup');
+const toc = generateTableOfContents(doc.html);
+
+toc.forEach(item => {
+  console.log(`${'  '.repeat(item.level - 2)}${item.text}`);
+});
+```
+
+## Next Steps
+
+Explore the [Routing System](/docs/routing) to learn more about how the system works.

package/docs/en/api/overview.md

@@ -0,0 +1,69 @@
+---
+title: API Overview
+description: Overview of the documentation system API
+author: Andrew
+date: 2026-02-05
+---
+
+# API Overview
+
+The documentation system provides utility functions for working with markdown files and routing.
+
+## Core Utilities
+
+### scanDocsFolder(docsPath: string)
+
+Scans the docs folder and returns a structure of all markdown files.
+
+```typescript
+const structure = await scanDocsFolder('./docs');
+// Returns: { 'setup': {...}, 'api/overview': {...} }
+```
+
+### loadMarkdownBySlug(docsPath: string, slug: string)
+
+Loads and parses a markdown file by its slug.
+
+```typescript
+const doc = await loadMarkdownBySlug('./docs', 'setup');
+// Returns: { content, html, metadata, slug, title }
+```
+
+### generateTableOfContents(htmlContent: string)
+
+Generates a table of contents from rendered markdown.
+
+```typescript
+const toc = generateTableOfContents(htmlContent);
+// Returns: [{ level: 2, text: 'Setup', id: 'setup' }, ...]
+```
+
+## Data Types
+
+### ParsedMarkdown
+
+```typescript
+interface ParsedMarkdown {
+  content: string;           // Raw markdown
+  html: string;              // Rendered HTML
+  metadata: FrontMatter;     // YAML frontmatter
+  slug: string;              // URL slug
+  title: string;             // Page title
+}
+```
+
+### FrontMatter
+
+```typescript
+interface FrontMatter {
+  title?: string;
+  description?: string;
+  author?: string;
+  date?: string;
+  [key: string]: any;        // Custom fields
+}
+```
+
+## Examples
+
+See [API Examples](/docs/api/examples) for complete code samples.