@alliance-droid/svelte-docs-system 0.0.1

package/bin/init.js

@@ -0,0 +1,821 @@
+#!/usr/bin/env node
+
+/**
+ * Initialize docs system in an existing SvelteKit project
+ * 
+ * Usage:
+ *   npx svelte-docs-system init [--route /docs] [--folder ./docs]
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import readline from 'readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = process.cwd();
+
+// Colors for console output
+const colors = {
+	reset: '\x1b[0m',
+	bright: '\x1b[1m',
+	green: '\x1b[32m',
+	yellow: '\x1b[33m',
+	blue: '\x1b[34m',
+	red: '\x1b[31m'
+};
+
+function log(message, color = 'reset') {
+	console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function error(message) {
+	console.error(`${colors.red}✘ Error: ${message}${colors.reset}`);
+	process.exit(1);
+}
+
+function success(message) {
+	log(`✓ ${message}`, 'green');
+}
+
+function info(message) {
+	log(`ℹ ${message}`, 'blue');
+}
+
+function warn(message) {
+	log(`⚠ ${message}`, 'yellow');
+}
+
+// Create readline interface for prompts
+const rl = readline.createInterface({
+	input: process.stdin,
+	output: process.stdout
+});
+
+function prompt(question) {
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			resolve(answer);
+		});
+	});
+}
+
+// Simple argument parser
+function parseArgs() {
+	const args = process.argv.slice(2);
+	const result = {
+		route: null,
+		folder: null
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === '--route' && args[i + 1]) {
+			result.route = args[i + 1];
+			i++;
+		} else if (args[i] === '--folder' && args[i + 1]) {
+			result.folder = args[i + 1];
+			i++;
+		}
+	}
+
+	return result;
+}
+
+async function main() {
+	try {
+		log('\n🚀 Initializing documentation system...', 'bright');
+
+		// Check if we're in a SvelteKit project
+		const svelteConfigPath = path.join(projectRoot, 'svelte.config.js');
+		if (!fs.existsSync(svelteConfigPath)) {
+			error('svelte.config.js not found. Please run this in a SvelteKit project root.');
+		}
+
+		// Get config options from args or prompts
+		const defaultRoute = '/docs';
+		const defaultFolder = './docs';
+		const args = parseArgs();
+
+		let finalRoute, finalFolder;
+
+		if (args.route && args.folder) {
+			// Non-interactive mode
+			finalRoute = args.route;
+			finalFolder = args.folder;
+			info(`Using route: ${finalRoute}`);
+			info(`Using folder: ${finalFolder}`);
+		} else {
+			// Interactive mode
+			log('\nConfiguration:', 'bright');
+			const docsRoute = await prompt(
+				`Enter docs route (default: ${defaultRoute}): `
+			);
+			finalRoute = docsRoute.trim() || defaultRoute;
+
+			const docsFolder = await prompt(
+				`Enter docs folder path (default: ${defaultFolder}): `
+			);
+			finalFolder = docsFolder.trim() || defaultFolder;
+
+			info(`Using route: ${finalRoute}`);
+			info(`Using folder: ${finalFolder}`);
+		}
+
+		// Create docs folder structure
+		log('\nCreating folder structure...', 'bright');
+		const docsFolderPath = path.join(projectRoot, finalFolder);
+		const apiFolderPath = path.join(docsFolderPath, 'api');
+		const guidesFolderPath = path.join(docsFolderPath, 'guides');
+
+		// Create directories
+		[docsFolderPath, apiFolderPath, guidesFolderPath].forEach((dir) => {
+			if (!fs.existsSync(dir)) {
+				fs.mkdirSync(dir, { recursive: true });
+				success(`Created directory: ${path.relative(projectRoot, dir)}`);
+			} else {
+				warn(`Directory already exists: ${path.relative(projectRoot, dir)}`);
+			}
+		});
+
+		// Create example markdown files
+		log('\nCreating example documentation...', 'bright');
+		createMarkdownFiles(docsFolderPath, finalRoute);
+
+		// Create route handlers
+		log('\nCreating route handlers...', 'bright');
+		createRouteHandlers(projectRoot, finalRoute, finalFolder);
+
+		// Update svelte.config.js
+		log('\nUpdating svelte.config.js...', 'bright');
+		updateSvelteConfig(svelteConfigPath, finalRoute, finalFolder);
+
+		// Create navigation config
+		log('\nCreating navigation config...', 'bright');
+		createNavConfig(docsFolderPath, finalRoute);
+
+		log('\n✨ Documentation system initialized!', 'green');
+		log(`\nNext steps:`, 'bright');
+		log(`  1. Start dev server: npm run dev`);
+		log(`  2. Visit: http://localhost:5173${finalRoute}`);
+		log(`  3. Edit markdown files in ${finalFolder}/ to customize docs`);
+		log(`  4. Edit ${finalFolder}/_config.json to customize navigation\n`);
+
+		rl.close();
+	} catch (err) {
+		error(err.message);
+	}
+}
+
+function createMarkdownFiles(docsFolderPath, docsRoute) {
+	const files = {
+		'index.md': `---
+title: Documentation Home
+description: Welcome to your documentation
+author: Your Name
+date: ${new Date().toISOString().split('T')[0]}
+---
+
+# Welcome to Your Documentation
+
+This is the home page of your documentation site.
+
+## Getting Started
+
+- Check out the [Setup Guide](${docsRoute}/setup) to get started
+- Read the [Architecture Guide](${docsRoute}/guides/architecture) for an overview
+- Visit the [API Reference](${docsRoute}/api/overview) for detailed API docs
+
+## Features
+
+- **Automatic routing** from markdown files
+- **Nested paths** support (organize docs in folders)
+- **Frontmatter metadata** (title, author, date)
+- **Professional styling** out of the box
+- **Easy to customize** and extend
+
+## Project Structure
+
+\`\`\`
+${path.basename(docsFolderPath)}/
+├── index.md                 (This file)
+├── setup.md                 (Getting started)
+├── api/
+│   ├── overview.md          (API overview)
+│   └── reference.md         (API reference)
+└── guides/
+    ├── architecture.md      (Architecture guide)
+    └── advanced.md          (Advanced topics)
+\`\`\`
+
+Each markdown file automatically becomes a route. For example:
+- \`${path.basename(docsFolderPath)}/setup.md\` → \`${docsRoute}/setup\`
+- \`${path.basename(docsFolderPath)}/api/overview.md\` → \`${docsRoute}/api/overview\`
+`,
+		'setup.md': `---
+title: Setup Guide
+description: Get started with your documentation
+author: Your Name
+date: ${new Date().toISOString().split('T')[0]}
+---
+
+# Setup Guide
+
+This guide will help you get started with your documentation.
+
+## Prerequisites
+
+- Node.js 18 or higher
+- npm, pnpm, or yarn
+
+## Installation
+
+If you haven't already, install the dependencies:
+
+\`\`\`bash
+npm install
+\`\`\`
+
+## Starting Development
+
+Start the development server:
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+Visit \`http://localhost:5173\` in your browser.
+
+## Creating Documentation
+
+1. Create new markdown files in the \`docs/\` folder
+2. Use frontmatter for metadata (title, description, author, date)
+3. Organize files in folders for nested routing
+4. Markdown files automatically become routes
+
+### Example
+
+Create \`docs/guides/my-guide.md\`:
+
+\`\`\`markdown
+---
+title: My Guide
+description: A guide about something
+---
+
+# My Guide
+
+Content goes here...
+\`\`\`
+
+This creates a route: \`/docs/guides/my-guide\`
+
+## Customization
+
+Edit \`docs/_config.json\` to customize the navigation structure. See the comments in that file for options.
+
+## Next Steps
+
+- Read the [API Reference](/docs/api/overview)
+- Explore the [Architecture Guide](/docs/guides/architecture)
+`,
+		'api/overview.md': `---
+title: API Overview
+description: API documentation overview
+author: Your Name
+date: ${new Date().toISOString().split('T')[0]}
+---
+
+# API Overview
+
+This page provides an overview of your API.
+
+## Base URL
+
+\`\`\`
+https://api.example.com/v1
+\`\`\`
+
+## Authentication
+
+Include your API key in the request headers:
+
+\`\`\`bash
+curl -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/v1/...
+\`\`\`
+
+## Response Format
+
+All responses are JSON:
+
+\`\`\`json
+{
+  "success": true,
+  "data": { /* ... */ }
+}
+\`\`\`
+
+## Endpoints
+
+For detailed endpoint documentation, see the [API Reference](/docs/api/reference).
+
+## Rate Limiting
+
+API requests are rate limited to 1000 per hour per API key.
+`,
+		'api/reference.md': `---
+title: API Reference
+description: Complete API reference documentation
+author: Your Name
+date: ${new Date().toISOString().split('T')[0]}
+---
+
+# API Reference
+
+Complete documentation of all API endpoints.
+
+## GET /users
+
+Retrieve a list of users.
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| page | integer | Page number (default: 1) |
+| limit | integer | Results per page (default: 10) |
+
+### Example
+
+\`\`\`bash
+curl https://api.example.com/v1/users?page=1&limit=10
+\`\`\`
+
+### Response
+
+\`\`\`json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "user_123",
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  ]
+}
+\`\`\`
+
+## POST /users
+
+Create a new user.
+
+### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | User's full name |
+| email | string | Yes | User's email address |
+
+### Example
+
+\`\`\`bash
+curl -X POST https://api.example.com/v1/users \\
+  -H "Content-Type: application/json" \\
+  -d '{"name":"Jane Doe","email":"jane@example.com"}'
+\`\`\`
+
+### Response
+
+\`\`\`json
+{
+  "success": true,
+  "data": {
+    "id": "user_456",
+    "name": "Jane Doe",
+    "email": "jane@example.com"
+  }
+}
+\`\`\`
+`,
+		'guides/architecture.md': `---
+title: Architecture Guide
+description: Overview of the system architecture
+author: Your Name
+date: ${new Date().toISOString().split('T')[0]}
+---
+
+# Architecture Guide
+
+This guide explains the high-level architecture of the system.
+
+## Overview
+
+The system is built with modern web technologies:
+
+- **Frontend:** SvelteKit with Svelte 5
+- **Styling:** Tailwind CSS
+- **Build Tool:** Vite
+- **Documentation:** This markdown-based system
+
+## Components
+
+### Documentation System
+
+The documentation system automatically:
+
+- Converts markdown files to web pages
+- Generates navigation from folder structure
+- Provides search functionality
+- Handles dark mode and responsive design
+
+### Adding Custom Components
+
+You can add custom Svelte components to your markdown files by extending the markdown processor.
+
+## Data Flow
+
+\`\`\`
+User navigates to /docs/page
+  ↓
+SvelteKit router matches route
+  ↓
+Page loader fetches markdown file
+  ↓
+Markdown is parsed and converted to HTML
+  ↓
+Components are rendered with Svelte
+  ↓
+Page is displayed in browser
+\`\`\`
+
+## Performance
+
+- Static file serving for fast load times
+- Optimized image delivery
+- Minimal JavaScript by default
+- Full-text search via Pagefind
+
+## Customization
+
+All components can be customized by:
+
+1. Overriding styles via Tailwind CSS
+2. Creating custom Svelte components
+3. Modifying the layout templates
+
+See the configuration guide for more details.
+`,
+		'guides/advanced.md': `---
+title: Advanced Topics
+description: Advanced usage and customization
+author: Your Name
+date: ${new Date().toISOString().split('T')[0]}
+---
+
+# Advanced Topics
+
+This guide covers advanced usage and customization topics.
+
+## Custom Components in Markdown
+
+Create reusable components for your documentation:
+
+\`\`\`svelte
+<script>
+  export let type = 'info';
+</script>
+
+<div class="custom-component {type}">
+  <slot />
+</div>
+\`\`\`
+
+Then use them in markdown:
+
+\`\`\`markdown
+<CustomComponent type="warning">
+  This is important!
+</CustomComponent>
+\`\`\`
+
+## Extending the Theme
+
+Customize the theme by:
+
+1. Modifying Tailwind CSS configuration
+2. Overriding component styles
+3. Creating custom layout templates
+
+## SEO Optimization
+
+Each markdown file supports frontmatter metadata:
+
+- \`title\` - Page title (shown in browser tab)
+- \`description\` - Meta description (shown in search results)
+- \`author\` - Author name
+- \`date\` - Last modified date
+
+These are automatically converted to meta tags.
+
+## Version Management
+
+You can maintain multiple versions of documentation:
+
+\`\`\`
+docs/
+├── v1/
+│   ├── index.md
+│   └── api/
+├── v2/
+│   ├── index.md
+│   └── api/
+└── latest -> v2  (symlink or config)
+\`\`\`
+
+## Troubleshooting
+
+### Pages not appearing
+
+Make sure markdown files are in the \`docs/\` folder and have \`.md\` extension.
+
+### Styling issues
+
+Clear the \`.svelte-kit\` and \`node_modules\` folders and rebuild:
+
+\`\`\`bash
+rm -rf .svelte-kit node_modules
+npm install
+npm run build
+\`\`\`
+
+### Search not working
+
+Ensure the project is built:
+
+\`\`\`bash
+npm run build
+\`\`\`
+
+Search only works with built pages.
+`
+	};
+
+	for (const [filename, content] of Object.entries(files)) {
+		const filePath = path.join(docsFolderPath, filename);
+		const dirPath = path.dirname(filePath);
+
+		if (!fs.existsSync(dirPath)) {
+			fs.mkdirSync(dirPath, { recursive: true });
+		}
+
+		if (!fs.existsSync(filePath)) {
+			fs.writeFileSync(filePath, content);
+			success(`Created: ${path.relative(projectRoot, filePath)}`);
+		} else {
+			warn(`File already exists: ${path.relative(projectRoot, filePath)}`);
+		}
+	}
+}
+
+function createRouteHandlers(projectRoot, docsRoute, docsFolder) {
+	const routePath = path.join(projectRoot, 'src/routes');
+	const docsRouteName = docsRoute.substring(1); // Remove leading /
+
+	// Create the docs route folder
+	const docsRouteFolder = path.join(routePath, docsRouteName);
+	if (!fs.existsSync(docsRouteFolder)) {
+		fs.mkdirSync(docsRouteFolder, { recursive: true });
+		success(`Created directory: src/routes/${docsRouteName}`);
+	}
+
+	// Create the dynamic route folder
+	const dynamicFolder = path.join(docsRouteFolder, '[...slug]');
+	if (!fs.existsSync(dynamicFolder)) {
+		fs.mkdirSync(dynamicFolder, { recursive: true });
+		success(`Created directory: src/routes/${docsRouteName}/[...slug]`);
+	}
+
+	// Create layout.svelte
+	const layoutContent = `<script lang="ts">
+	import { DocLayout } from 'svelte-docs-system';
+	import { onMount } from 'svelte';
+	
+	let config = {};
+	
+	onMount(async () => {
+		// Load nav config if _config.json exists
+		try {
+			const response = await fetch('${docsRoute}/_config.json');
+			if (response.ok) {
+				config = await response.json();
+			}
+		} catch (e) {
+			// Config file not found, use defaults
+		}
+	});
+</script>
+
+<DocLayout {config}>
+	<slot />
+</DocLayout>
+`;
+
+	const layoutPath = path.join(docsRouteFolder, '+layout.svelte');
+	if (!fs.existsSync(layoutPath)) {
+		fs.writeFileSync(layoutPath, layoutContent);
+		success(`Created: src/routes/${docsRouteName}/+layout.svelte`);
+	} else {
+		warn(`File already exists: src/routes/${docsRouteName}/+layout.svelte`);
+	}
+
+	// Create +page.svelte for dynamic route
+	const pageContent = `<script lang="ts" context="module">
+	import { dev } from '$app/environment';
+	
+	export async function load({ params }) {
+		const slug = params.slug || 'index';
+		const docPath = '${docsRoute}/\${slug}.md';
+		
+		try {
+			const response = await fetch(docPath);
+			if (!response.ok) {
+				return {
+					status: 404,
+					error: new Error('Documentation page not found')
+				};
+			}
+			
+			const content = await response.text();
+			return {
+				props: {
+					content,
+					slug
+				}
+			};
+		} catch (error) {
+			return {
+				status: 500,
+				error: new Error('Failed to load documentation')
+			};
+		}
+	}
+</script>
+
+<script>
+	import { renderMarkdown } from 'svelte-docs-system';
+	
+	export let data;
+	
+	let { html = '', metadata = {} } = renderMarkdown(data.props?.content || '') || {};
+</script>
+
+<svelte:head>
+	<title>{metadata.title || 'Documentation'} | Docs</title>
+	<meta name="description" content={metadata.description || 'Documentation'} />
+</svelte:head>
+
+<article>
+	{@html html}
+</article>
+
+<style>
+	:global(article) {
+		max-width: 900px;
+		margin: 0 auto;
+		padding: 2rem;
+	}
+	
+	:global(article h1) {
+		font-size: 2.5rem;
+		margin-bottom: 1rem;
+	}
+	
+	:global(article h2) {
+		font-size: 1.875rem;
+		margin-top: 2rem;
+		margin-bottom: 1rem;
+	}
+	
+	:global(article p) {
+		line-height: 1.75;
+		margin-bottom: 1rem;
+	}
+	
+	:global(article code) {
+		background-color: #f3f4f6;
+		padding: 0.125rem 0.5rem;
+		border-radius: 0.25rem;
+		font-family: 'Courier New', monospace;
+	}
+	
+	:global(article pre) {
+		background-color: #1f2937;
+		color: #f3f4f6;
+		padding: 1rem;
+		border-radius: 0.5rem;
+		overflow-x: auto;
+		margin-bottom: 1rem;
+	}
+	
+	:global(article pre code) {
+		background-color: transparent;
+		padding: 0;
+		color: inherit;
+	}
+</style>
+`;
+
+	const pagePath = path.join(dynamicFolder, '+page.svelte');
+	if (!fs.existsSync(pagePath)) {
+		fs.writeFileSync(pagePath, pageContent);
+		success(`Created: src/routes/${docsRouteName}/[...slug]/+page.svelte`);
+	} else {
+		warn(`File already exists: src/routes/${docsRouteName}/[...slug]/+page.svelte`);
+	}
+}
+
+function updateSvelteConfig(configPath, docsRoute, docsFolder) {
+	let config = fs.readFileSync(configPath, 'utf-8');
+
+	// Check if docs plugin is already registered
+	if (config.includes('docs plugin')) {
+		warn('Docs plugin appears to already be configured in svelte.config.js');
+		return;
+	}
+
+	// Insert plugin configuration
+	const pluginConfig = `\timport { docs } from 'svelte-docs-system';\n\n`;
+	const pluginInConfig = `\t\tdocs({
+\t\t\tdocsRoute: '${docsRoute}',
+\t\t\tdocsFolderPath: '${docsFolder}',
+\t\t\tbasePath: '${docsRoute}'
+\t\t}),`;
+
+	// Add import at the top
+	if (!config.includes("from 'svelte-docs-system'")) {
+		const firstImportIndex = config.indexOf('import');
+		config = config.slice(0, firstImportIndex) + pluginConfig + config.slice(firstImportIndex);
+	}
+
+	// Add to plugins array if exists
+	const pluginsIndex = config.indexOf('plugins:');
+	if (pluginsIndex !== -1) {
+		const arrayStart = config.indexOf('[', pluginsIndex);
+		const insertPos = arrayStart + 1;
+		config = config.slice(0, insertPos) + '\n' + pluginInConfig + '\n' + config.slice(insertPos);
+	} else {
+		// Add plugins section
+		const kitClosing = config.lastIndexOf('}');
+		const plugins = `,\n\t\tplugins: [
+${pluginInConfig}
+\t\t]`;
+		config = config.slice(0, kitClosing) + plugins + config.slice(kitClosing);
+	}
+
+	fs.writeFileSync(configPath, config);
+	success('Updated svelte.config.js with docs plugin');
+}
+
+function createNavConfig(docsFolderPath, docsRoute) {
+	const configPath = path.join(docsFolderPath, '_config.json');
+
+	if (fs.existsSync(configPath)) {
+		warn(`Navigation config already exists: _config.json`);
+		return;
+	}
+
+	const navConfig = {
+		name: 'Documentation',
+		baseUrl: docsRoute,
+		sections: [
+			{
+				title: 'Getting Started',
+				pages: [
+					{ label: 'Home', path: docsRoute },
+					{ label: 'Setup', path: `${docsRoute}/setup` }
+				]
+			},
+			{
+				title: 'API',
+				pages: [
+					{ label: 'Overview', path: `${docsRoute}/api/overview` },
+					{ label: 'Reference', path: `${docsRoute}/api/reference` }
+				]
+			},
+			{
+				title: 'Guides',
+				pages: [
+					{ label: 'Architecture', path: `${docsRoute}/guides/architecture` },
+					{ label: 'Advanced', path: `${docsRoute}/guides/advanced` }
+				]
+			}
+		]
+	};
+
+	fs.writeFileSync(configPath, JSON.stringify(navConfig, null, 2));
+	success('Created: docs/_config.json');
+}
+
+// Run the main function
+main();