@alliance-droid/svelte-docs-system 0.0.1

package/docs/en/getting-started/integration.md

@@ -0,0 +1,406 @@
+---
+title: Integration Guide
+description: Add the SvelteKit Documentation System to an existing project
+author: Andrew
+date: 2026-02-05
+---
+
+# Integration Guide
+
+Learn how to add the SvelteKit Documentation System to your existing SvelteKit project.
+
+## Overview
+
+The SvelteKit Documentation System is designed to integrate seamlessly into existing SvelteKit applications. It provides:
+
+- **Folder-based routing** - Markdown files automatically become routes
+- **Professional theme** - Claude Code aesthetic with dark mode support
+- **Zero configuration** - Works out of the box with sensible defaults
+- **Highly customizable** - Adjust colors, layout, and behavior as needed
+- **Configurable mount point** - Place docs at `/docs`, `/help`, `/guides`, or any route
+
+## Prerequisites
+
+- Existing SvelteKit project (v2.0+)
+- Node.js 18+
+- npm, pnpm, or yarn
+
+## Step 1: Install Dependencies
+
+First, ensure you have the required dependencies in your SvelteKit project:
+
+```bash
+npm install
+```
+
+The documentation system components are already included in your SvelteKit setup and use:
+- Svelte 5 (with Runes)
+- Tailwind CSS 4
+- TypeScript
+
+## Step 2: Create Docs Folder Structure
+
+Create a `docs` folder in your project root with your markdown files:
+
+```bash
+mkdir -p docs
+mkdir -p docs/guides
+mkdir -p docs/api
+```
+
+Create your first documentation file:
+
+```bash
+cat > docs/index.md << 'EOF'
+---
+title: Documentation Home
+description: Welcome to our documentation
+---
+
+# Welcome to Our Documentation
+
+This is the home page of your documentation site.
+
+## Quick Links
+
+- [Getting Started](/docs/getting-started)
+- [API Reference](/docs/api)
+- [Guides](/docs/guides)
+EOF
+```
+
+## Step 3: Create Routes
+
+Create the documentation routes in your SvelteKit app. Create `src/routes/docs/+layout.svelte`:
+
+```svelte
+<script lang="ts">
+  import DocLayout from '$lib/components/DocLayout.svelte';
+  import type { NavSection } from '$lib/stores/nav';
+  import { page } from '$app/stores';
+
+  const sections: NavSection[] = [
+    {
+      title: 'Getting Started',
+      items: [
+        { label: 'Home', href: '/docs' },
+        { label: 'Integration', href: '/docs/integration' },
+        { label: 'Setup', href: '/docs/setup' },
+      ],
+    },
+    {
+      title: 'Components',
+      items: [
+        { label: 'Overview', href: '/docs/components' },
+        { label: 'DocLayout', href: '/docs/components/doclayout' },
+        { label: 'Navbar', href: '/docs/components/navbar' },
+      ],
+    },
+    {
+      title: 'Configuration',
+      items: [
+        { label: 'Theme Colors', href: '/docs/config/theme' },
+        { label: 'Navigation', href: '/docs/config/navigation' },
+      ],
+    },
+  ];
+
+  let { children } = $props();
+</script>
+
+<DocLayout
+  title="Documentation"
+  logo={null}
+  {sections}
+  copyright="© 2026 Your Project"
+>
+  {@render children()}
+</DocLayout>
+```
+
+Create `src/routes/docs/[...slug]/+page.svelte` for dynamic routing:
+
+```svelte
+<script lang="ts">
+  import { dev } from '$app/environment';
+
+  let markdown = '';
+  let metadata = {
+    title: 'Not Found',
+    description: '',
+  };
+
+  export async function load({ params }) {
+    const slug = params.slug ? params.slug.join('/') : 'index';
+    const path = `/docs/${slug}.md`;
+
+    try {
+      const response = await fetch(path);
+      if (!response.ok) {
+        throw new Error('Not found');
+      }
+
+      const content = await response.text();
+      const { metadata: meta, html } = parseMarkdown(content);
+
+      return {
+        metadata: meta,
+        html,
+        slug,
+      };
+    } catch (e) {
+      if (dev) console.error(e);
+      return {
+        status: 404,
+        error: new Error('Documentation page not found'),
+      };
+    }
+  }
+
+  function parseMarkdown(content: string) {
+    // Simple frontmatter parser
+    const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    const metadata: Record<string, string> = {};
+
+    if (match) {
+      const frontmatter = match[1];
+      const body = match[2];
+
+      frontmatter.split('\n').forEach((line) => {
+        const [key, ...valueParts] = line.split(': ');
+        if (key && valueParts.length) {
+          metadata[key.trim()] = valueParts.join(': ').trim();
+        }
+      });
+
+      return {
+        metadata,
+        html: `<article class="prose"><h1>${metadata.title}</h1>${body}</article>`,
+      };
+    }
+
+    return {
+      metadata: { title: 'Untitled' },
+      html: `<article class="prose">${content}</article>`,
+    };
+  }
+</script>
+
+<svelte:head>
+  <title>{metadata.title} | Docs</title>
+  <meta name="description" content={metadata.description} />
+</svelte:head>
+
+{@html html}
+```
+
+## Step 4: Copy Components to Your Project
+
+If not already present, copy the documentation components to your project:
+
+```bash
+cp -r src/lib/components ~/your-project/src/lib/
+```
+
+Ensure these components are available:
+- `DocLayout.svelte`
+- `Navbar.svelte`
+- `Sidebar.svelte`
+- `Footer.svelte`
+- `Callout.svelte`
+- `CodeBlock.svelte`
+
+## Step 5: Configure Tailwind CSS
+
+Ensure your `tailwind.config.ts` includes the Claude Code theme colors:
+
+```typescript
+import type { Config } from 'tailwindcss';
+
+export default {
+  content: ['./src/**/*.{html,js,svelte,ts}'],
+  theme: {
+    extend: {
+      colors: {
+        'claude-bg': '#FFFFFF',
+        'claude-bg-secondary': '#F7F6F3',
+        'claude-text': '#1A1A1A',
+        'claude-text-secondary': '#565656',
+        'claude-border': '#ECECEC',
+        'claude-accent': '#0066CC',
+        'claude-accent-hover': '#0052A3',
+        'claude-dark-bg': '#1A1A1A',
+        'claude-dark-bg-secondary': '#2D2D2D',
+        'claude-dark-text': '#FFFFFF',
+        'claude-dark-text-secondary': '#B0B0B0',
+        'claude-dark-border': '#3A3A3A',
+        'claude-dark-accent': '#4D94FF',
+        'claude-dark-accent-hover': '#6BA3FF',
+      },
+    },
+  },
+  darkMode: 'class',
+  plugins: [],
+} satisfies Config;
+```
+
+## Step 6: Start Your Development Server
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:5173/docs` in your browser to see your documentation site!
+
+## Configuring the Mount Point
+
+By default, documentation is mounted at `/docs`. To use a different route (e.g., `/help` or `/guides`):
+
+### Change the Route File Location
+
+Instead of `src/routes/docs/`, create `src/routes/help/`:
+
+```bash
+mkdir -p src/routes/help
+# Copy the files from docs to help
+cp src/routes/docs/+layout.svelte src/routes/help/+layout.svelte
+cp -r src/routes/docs/[...slug] src/routes/help/
+```
+
+### Update Links in Layout
+
+Update all href values in your layout from `/docs` to `/help`:
+
+```svelte
+const sections: NavSection[] = [
+  {
+    title: 'Getting Started',
+    items: [
+      { label: 'Home', href: '/help' },
+      { label: 'Setup', href: '/help/setup' },
+    ],
+  },
+];
+```
+
+## Directory Structure After Integration
+
+Your project should look like this:
+
+```
+your-project/
+├── src/
+│   ├── lib/
+│   │   ├── components/           (Documentation components)
+│   │   │   ├── DocLayout.svelte
+│   │   │   ├── Navbar.svelte
+│   │   │   └── ...
+│   │   └── stores/               (Theme and nav stores)
+│   │       ├── theme.ts
+│   │       └── nav.ts
+│   ├── routes/
+│   │   ├── +layout.svelte        (Your main layout)
+│   │   ├── docs/                 (Docs routes - NEW)
+│   │   │   ├── +layout.svelte
+│   │   │   └── [...slug]/
+│   │   │       └── +page.svelte
+│   │   ├── other-routes/         (Your existing routes)
+│   │   └── ...
+│   ├── app.css                   (Global styles with Tailwind)
+│   └── app.svelte
+├── docs/                         (Markdown files - NEW)
+│   ├── index.md
+│   ├── setup.md
+│   ├── api/
+│   │   └── overview.md
+│   └── guides/
+│       └── getting-started.md
+├── tailwind.config.ts
+├── svelte.config.js
+└── package.json
+```
+
+## Best Practices
+
+### Organizing Your Documentation
+
+```
+docs/
+├── index.md                 (Home/Introduction)
+├── getting-started/
+│   ├── index.md            (Getting started overview)
+│   ├── installation.md      (Installation steps)
+│   └── quick-start.md       (Quick start guide)
+├── guides/
+│   ├── api-integration.md   (API integration guide)
+│   ├── theming.md           (Theming guide)
+│   └── deployment.md        (Deployment guide)
+├── api/
+│   ├── index.md            (API overview)
+│   ├── components.md       (Component reference)
+│   └── stores.md           (Store reference)
+└── troubleshooting.md       (Troubleshooting guide)
+```
+
+### Markdown Files
+
+Each markdown file should start with frontmatter:
+
+```markdown
+---
+title: Your Page Title
+description: Brief description for SEO
+author: Your Name
+date: 2026-02-05
+---
+
+# Your Page Title
+
+Content goes here...
+```
+
+### Linking Between Pages
+
+Use relative paths for links:
+
+```markdown
+- [Getting Started](/docs/getting-started)
+- [API Reference](/docs/api)
+- [Troubleshooting](/docs/troubleshooting)
+```
+
+## Troubleshooting Integration
+
+### Routes Not Working
+
+**Problem:** Documentation pages return 404
+
+**Solution:**
+1. Ensure `docs/` folder exists in project root
+2. Check file names match URLs (no spaces, use hyphens)
+3. Verify `+layout.svelte` and `[...slug]/+page.svelte` are in `src/routes/docs/`
+
+### Styling Not Applied
+
+**Problem:** Pages appear unstyled
+
+**Solution:**
+1. Verify Tailwind CSS is configured in `tailwind.config.ts`
+2. Ensure `src/app.css` includes `@tailwind` directives
+3. Check that `DocLayout` component is imported in `+layout.svelte`
+
+### Sidebar Not Showing Navigation
+
+**Problem:** Sidebar appears empty
+
+**Solution:**
+1. Verify `sections` array is populated with navigation items
+2. Check that `href` values start with your docs mount point (e.g., `/docs`)
+3. Ensure `NavSection` and `NavItem` types match the store definitions
+
+## Next Steps
+
+- [Configure Theme Colors](/docs/config/theme)
+- [Learn About Components](/docs/components)
+- [Create Custom Navigation](/docs/config/navigation)
+- [Deploy Your Docs](/docs/guides/deployment)