@alliance-droid/svelte-docs-system 0.0.2 → 0.1.0

package/{template-starter/src/lib/index.ts → dist/index.d.ts}

@@ -1,5 +1,6 @@
-// Re-export documentation components for use in your templates
-
+export { default as Documentation } from './components/Documentation.svelte';
+export { svelteDocsPlugin, default as docsPlugin } from './plugin.js';
+export type { DocsPluginOptions, DocFile, DocFolder } from './plugin.js';
 export { default as Callout } from './components/Callout.svelte';
 export { default as Tabs } from './components/Tabs.svelte';
 export { default as CodeBlock } from './components/CodeBlock.svelte';
@@ -7,9 +8,7 @@ export { default as Image } from './components/Image.svelte';
 export { default as APITable } from './components/APITable.svelte';
 export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
 export { default as Search } from './components/Search.svelte';
-
-// Re-export theme components
-export { default as DocLayout } from './components/DocLayout.svelte';
-export { default as Navbar } from './components/Navbar.svelte';
 export { default as Sidebar } from './components/Sidebar.svelte';
-export { default as Footer } from './components/Footer.svelte';
+export { renderMarkdown, renderMarkdownSync, extractMetadata, getExcerpt, type MarkdownMetadata, type MarkdownResult, } from './utils/index.js';
+export { theme } from './stores/theme';
+export { sidebarOpen } from './stores/nav';

package/dist/index.js

@@ -0,0 +1,18 @@
+// Main component - drop this into your +page.svelte
+export { default as Documentation } from './components/Documentation.svelte';
+// Vite plugin - add to vite.config.ts
+export { svelteDocsPlugin, default as docsPlugin } from './plugin.js';
+// Content components for custom layouts
+export { default as Callout } from './components/Callout.svelte';
+export { default as Tabs } from './components/Tabs.svelte';
+export { default as CodeBlock } from './components/CodeBlock.svelte';
+export { default as Image } from './components/Image.svelte';
+export { default as APITable } from './components/APITable.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as Search } from './components/Search.svelte';
+export { default as Sidebar } from './components/Sidebar.svelte';
+// Utilities
+export { renderMarkdown, renderMarkdownSync, extractMetadata, getExcerpt, } from './utils/index.js';
+// Stores (for advanced usage)
+export { theme } from './stores/theme';
+export { sidebarOpen } from './stores/nav';

package/dist/navigationBuilder.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Navigation builder for generating navigation from folder structure or config
+ */
+import type { NavItem, NavSection, NavigationConfig } from './config';
+export interface FileInfo {
+    /** Full file path (e.g., docs/api/overview.md) */
+    path: string;
+    /** File name without extension (e.g., overview) */
+    name: string;
+    /** File title (from frontmatter or derived from name) */
+    title?: string;
+    /** File order (from frontmatter) */
+    order?: number;
+    /** Is this the index file? */
+    isIndex: boolean;
+}
+/**
+ * Convert a file name to a display title
+ * Example: "api-reference" -> "API Reference"
+ */
+export declare function formatFileName(name: string): string;
+/**
+ * Parse file information from path
+ * Example: "docs/api/reference.md" -> { path: "docs/api/reference.md", name: "reference", isIndex: false }
+ */
+export declare function parseFileInfo(filePath: string, fileMetadata?: {
+    title?: string;
+    order?: number;
+}): FileInfo;
+/**
+ * Generate navigation from a list of files
+ * Useful for auto-generating sidebar from folder structure
+ */
+export declare function generateNavigationFromFiles(files: FileInfo[], baseRoute?: string): NavSection[];
+/**
+ * Flatten navigation sections to a single array of NavItems
+ */
+export declare function flattenNavigation(sections: NavSection[]): NavItem[];
+/**
+ * Validate navigation configuration
+ */
+export declare function validateNavigation(nav: NavigationConfig): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Filter files based on exclude patterns
+ */
+export declare function filterFiles(files: FileInfo[], excludePatterns?: string[]): FileInfo[];
+/**
+ * Build navigation from a config object
+ */
+export declare function buildNavigationFromConfig(config: NavigationConfig, files?: FileInfo[], baseRoute?: string): NavSection[];
+/**
+ * Find a navigation item by href
+ */
+export declare function findNavItem(sections: NavSection[], href: string): NavItem | null;
+/**
+ * Get previous and next navigation items in order
+ */
+export declare function getPrevNext(sections: NavSection[], currentHref: string): {
+    prev: NavItem | null;
+    next: NavItem | null;
+};

package/dist/navigationBuilder.js

@@ -0,0 +1,225 @@
+/**
+ * Navigation builder for generating navigation from folder structure or config
+ */
+/**
+ * Convert a file name to a display title
+ * Example: "api-reference" -> "API Reference"
+ */
+export function formatFileName(name) {
+    return name
+        .replace(/[-_]/g, ' ') // Replace hyphens and underscores with spaces
+        .replace(/\b\w/g, (char) => char.toUpperCase()); // Capitalize first letter of each word
+}
+/**
+ * Parse file information from path
+ * Example: "docs/api/reference.md" -> { path: "docs/api/reference.md", name: "reference", isIndex: false }
+ */
+export function parseFileInfo(filePath, fileMetadata) {
+    const cleanPath = filePath.replace(/^\.\//, ''); // Remove leading ./
+    const lastSlash = cleanPath.lastIndexOf('/');
+    const fileName = cleanPath.substring(lastSlash + 1);
+    const name = fileName.replace(/\.md$/, '');
+    return {
+        path: cleanPath,
+        name,
+        title: fileMetadata?.title || formatFileName(name),
+        order: fileMetadata?.order,
+        isIndex: name === 'index',
+    };
+}
+/**
+ * Group files by directory
+ */
+function groupFilesByDirectory(files) {
+    const groups = new Map();
+    files.forEach((file) => {
+        const match = file.path.match(/^docs\/(.+)\/[^/]+\.md$/);
+        const dir = match ? match[1] : 'root';
+        if (!groups.has(dir)) {
+            groups.set(dir, []);
+        }
+        groups.get(dir).push(file);
+    });
+    return groups;
+}
+/**
+ * Sort files by order, then alphabetically
+ */
+function sortFiles(files) {
+    return [...files].sort((a, b) => {
+        // Priority to index files at the top
+        if (a.isIndex && !b.isIndex)
+            return -1;
+        if (!a.isIndex && b.isIndex)
+            return 1;
+        // Then sort by order if specified
+        if (a.order !== undefined && b.order !== undefined) {
+            return a.order - b.order;
+        }
+        if (a.order !== undefined)
+            return -1;
+        if (b.order !== undefined)
+            return 1;
+        // Finally alphabetically
+        return a.name.localeCompare(b.name);
+    });
+}
+/**
+ * Generate navigation from a list of files
+ * Useful for auto-generating sidebar from folder structure
+ */
+export function generateNavigationFromFiles(files, baseRoute = '/docs') {
+    const groups = groupFilesByDirectory(files);
+    const sections = [];
+    // Process files in natural order
+    const sortedDirs = Array.from(groups.keys()).sort((a, b) => {
+        if (a === 'root')
+            return -1;
+        if (b === 'root')
+            return 1;
+        return a.localeCompare(b);
+    });
+    sortedDirs.forEach((dir) => {
+        const dirFiles = sortFiles(groups.get(dir));
+        if (dir === 'root') {
+            // Root files go to main section
+            dirFiles.forEach((file) => {
+                if (!file.isIndex) {
+                    if (!sections[0]) {
+                        sections.push({ title: 'Documentation', items: [] });
+                    }
+                    sections[0].items.push({
+                        label: file.title || file.name,
+                        href: `${baseRoute}/${file.name}`,
+                    });
+                }
+            });
+        }
+        else {
+            // Directory files go to their own section
+            const sectionTitle = formatFileName(dir);
+            const items = dirFiles.map((file) => ({
+                label: file.title || file.name,
+                href: `${baseRoute}/${dir}/${file.name}`,
+            }));
+            sections.push({ title: sectionTitle, items });
+        }
+    });
+    return sections;
+}
+/**
+ * Flatten navigation sections to a single array of NavItems
+ */
+export function flattenNavigation(sections) {
+    const items = [];
+    sections.forEach((section) => {
+        items.push({
+            label: section.title,
+            children: section.items,
+        });
+    });
+    return items;
+}
+/**
+ * Validate navigation configuration
+ */
+export function validateNavigation(nav) {
+    const errors = [];
+    if (!nav || typeof nav !== 'object') {
+        return { valid: false, errors: ['Navigation must be an object'] };
+    }
+    if (nav.sections !== undefined) {
+        if (!Array.isArray(nav.sections)) {
+            errors.push('sections must be an array');
+        }
+        else {
+            nav.sections.forEach((section, idx) => {
+                if (!section.title) {
+                    errors.push(`Section ${idx}: missing title`);
+                }
+                if (!Array.isArray(section.items)) {
+                    errors.push(`Section ${idx}: items must be an array`);
+                }
+                else {
+                    section.items.forEach((item, itemIdx) => {
+                        if (!item.label) {
+                            errors.push(`Section ${idx}, item ${itemIdx}: missing label`);
+                        }
+                    });
+                }
+            });
+        }
+    }
+    if (nav.excludePaths !== undefined && !Array.isArray(nav.excludePaths)) {
+        errors.push('excludePaths must be an array');
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Filter files based on exclude patterns
+ */
+export function filterFiles(files, excludePatterns = []) {
+    return files.filter((file) => {
+        return !excludePatterns.some((pattern) => {
+            // Simple pattern matching (could be extended to regex)
+            return file.path.includes(pattern);
+        });
+    });
+}
+/**
+ * Build navigation from a config object
+ */
+export function buildNavigationFromConfig(config, files, baseRoute = '/docs') {
+    // If explicit sections are provided, use them
+    if (config.sections && config.sections.length > 0) {
+        return config.sections;
+    }
+    // Otherwise auto-generate from files
+    if (files && files.length > 0) {
+        const filtered = filterFiles(files, config.excludePaths);
+        return generateNavigationFromFiles(filtered, baseRoute);
+    }
+    // Return empty navigation
+    return [];
+}
+/**
+ * Find a navigation item by href
+ */
+export function findNavItem(sections, href) {
+    for (const section of sections) {
+        for (const item of section.items) {
+            if (item.href === href) {
+                return item;
+            }
+            if (item.children) {
+                const found = item.children.find((child) => child.href === href);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Get previous and next navigation items in order
+ */
+export function getPrevNext(sections, currentHref) {
+    const allItems = [];
+    sections.forEach((section) => {
+        section.items.forEach((item) => {
+            if (item.href)
+                allItems.push(item);
+            if (item.children) {
+                item.children.forEach((child) => {
+                    if (child.href)
+                        allItems.push(child);
+                });
+            }
+        });
+    });
+    const currentIndex = allItems.findIndex((item) => item.href === currentHref);
+    return {
+        prev: currentIndex > 0 ? allItems[currentIndex - 1] : null,
+        next: currentIndex < allItems.length - 1 ? allItems[currentIndex + 1] : null,
+    };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Vite plugin for svelte-docs-system
+ * Auto-scans /docs folder and generates navigation structure
+ */
+import type { Plugin } from 'vite';
+export interface DocFile {
+    slug: string;
+    path: string;
+    title: string;
+    description?: string;
+    order?: number;
+}
+export interface DocFolder {
+    name: string;
+    slug: string;
+    files: DocFile[];
+    folders: DocFolder[];
+    order?: number;
+}
+export interface DocsPluginOptions {
+    /** Path to docs folder relative to project root. Default: './docs' */
+    docsPath?: string;
+    /** Route where docs will be served. Default: '/documentation' */
+    route?: string;
+}
+/**
+ * Vite plugin for svelte-docs-system
+ */
+export declare function svelteDocsPlugin(options?: DocsPluginOptions): Plugin;
+export default svelteDocsPlugin;

package/dist/plugin.js

@@ -0,0 +1,172 @@
+/**
+ * Vite plugin for svelte-docs-system
+ * Auto-scans /docs folder and generates navigation structure
+ */
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+const VIRTUAL_MODULE_ID = 'virtual:svelte-docs';
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
+/**
+ * Extract frontmatter and title from markdown file
+ */
+function parseMarkdownFile(filePath) {
+    try {
+        const fileContent = fs.readFileSync(filePath, 'utf-8');
+        const { data, content } = matter(fileContent);
+        // Get title from frontmatter or first H1
+        let title = data.title;
+        if (!title) {
+            const h1Match = content.match(/^#\s+(.+)$/m);
+            title = h1Match ? h1Match[1] : path.basename(filePath, '.md');
+        }
+        return {
+            title,
+            description: data.description,
+            order: data.order ?? data.sidebar_position,
+            content
+        };
+    }
+    catch {
+        return {
+            title: path.basename(filePath, '.md'),
+            content: ''
+        };
+    }
+}
+/**
+ * Convert filename to readable title
+ */
+function slugToTitle(slug) {
+    return slug
+        .replace(/-/g, ' ')
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+/**
+ * Recursively scan docs folder
+ */
+function scanDocsFolder(dirPath, basePath = '') {
+    const name = path.basename(dirPath);
+    const slug = basePath || '/';
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    const files = [];
+    const folders = [];
+    // Check for folder config (index.md or _category_.json)
+    let folderOrder;
+    const indexPath = path.join(dirPath, 'index.md');
+    if (fs.existsSync(indexPath)) {
+        const { order } = parseMarkdownFile(indexPath);
+        folderOrder = order;
+    }
+    for (const entry of entries) {
+        const entryPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith('_') && !entry.name.startsWith('.')) {
+            // Recurse into subdirectory
+            const subSlug = basePath ? `${basePath}/${entry.name}` : entry.name;
+            folders.push(scanDocsFolder(entryPath, subSlug));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'index.md') {
+            // Parse markdown file
+            const fileSlug = entry.name.replace(/\.md$/, '');
+            const fullSlug = basePath ? `${basePath}/${fileSlug}` : fileSlug;
+            const { title, description, order } = parseMarkdownFile(entryPath);
+            files.push({
+                slug: fullSlug,
+                path: entryPath,
+                title,
+                description,
+                order
+            });
+        }
+    }
+    // Sort by order, then alphabetically
+    files.sort((a, b) => {
+        if (a.order !== undefined && b.order !== undefined)
+            return a.order - b.order;
+        if (a.order !== undefined)
+            return -1;
+        if (b.order !== undefined)
+            return 1;
+        return a.title.localeCompare(b.title);
+    });
+    folders.sort((a, b) => {
+        if (a.order !== undefined && b.order !== undefined)
+            return a.order - b.order;
+        if (a.order !== undefined)
+            return -1;
+        if (b.order !== undefined)
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+    return {
+        name: slugToTitle(name),
+        slug,
+        files,
+        folders,
+        order: folderOrder
+    };
+}
+/**
+ * Generate the docs structure as a module
+ */
+function generateDocsModule(docsPath, route) {
+    if (!fs.existsSync(docsPath)) {
+        // Return empty structure if docs folder doesn't exist
+        return `
+export const docsStructure = { name: 'Documentation', slug: '/', files: [], folders: [] };
+export const docsRoute = '${route}';
+export const allDocs = [];
+`;
+    }
+    const structure = scanDocsFolder(docsPath);
+    // Flatten all docs for search/lookup
+    const allDocs = [];
+    function collectDocs(folder) {
+        allDocs.push(...folder.files);
+        folder.folders.forEach(collectDocs);
+    }
+    collectDocs(structure);
+    return `
+export const docsStructure = ${JSON.stringify(structure, null, 2)};
+export const docsRoute = '${route}';
+export const allDocs = ${JSON.stringify(allDocs, null, 2)};
+`;
+}
+/**
+ * Vite plugin for svelte-docs-system
+ */
+export function svelteDocsPlugin(options = {}) {
+    const docsPath = options.docsPath || './docs';
+    const route = options.route || '/documentation';
+    let root;
+    return {
+        name: 'svelte-docs-system',
+        configResolved(config) {
+            root = config.root;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_MODULE_ID) {
+                return RESOLVED_VIRTUAL_MODULE_ID;
+            }
+        },
+        load(id) {
+            if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                const fullDocsPath = path.resolve(root, docsPath);
+                return generateDocsModule(fullDocsPath, route);
+            }
+        },
+        handleHotUpdate({ file, server }) {
+            // Reload when docs files change
+            const fullDocsPath = path.resolve(root, docsPath);
+            if (file.startsWith(fullDocsPath) && file.endsWith('.md')) {
+                const module = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+                if (module) {
+                    server.moduleGraph.invalidateModule(module);
+                    return [module];
+                }
+            }
+        }
+    };
+}
+export default svelteDocsPlugin;

package/dist/routing.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Routing utilities for customizable documentation mount points
+ */
+import type { ConfigOptions } from './config';
+export interface RouteConfig {
+    /** Mount point for documentation (e.g., /docs, /help, /guides) */
+    docsRoute: string;
+    /** Path to docs folder relative to project root */
+    docsFolderPath: string;
+    /** Base path for links */
+    basePath: string;
+}
+/**
+ * Converts a route slug to a markdown file path
+ * Example: slug="api/overview", docsFolderPath="./docs" -> "./docs/api/overview.md"
+ */
+export declare function slugToFilePath(slug: string | string[], docsFolderPath: string): string;
+/**
+ * Converts a file path to a route URL
+ * Example: filePath="./docs/api/overview.md", docsRoute="/docs" -> "/docs/api/overview"
+ */
+export declare function filePathToRoute(filePath: string, docsRoute: string): string;
+/**
+ * Generates a list of all doc routes from a folder structure
+ * This would typically be called at build time to pre-generate routes
+ */
+export declare function generateDocRoutes(files: string[], docsRoute?: string, docsFolderPath?: string): string[];
+/**
+ * Validates a docs route
+ */
+export declare function validateRoute(route: string): boolean;
+/**
+ * Create route configuration from ConfigOptions
+ */
+export declare function createRouteConfig(config: ConfigOptions): RouteConfig;
+/**
+ * Build a navigation link using the docs route
+ */
+export declare function buildNavLink(slug: string, docsRoute?: string, absolute?: boolean): string;
+/**
+ * Extract slug from a docs route
+ * Example: "/docs/api/overview" with docsRoute="/docs" -> "api/overview"
+ */
+export declare function extractSlugFromRoute(fullRoute: string, docsRoute: string): string;
+/**
+ * Check if a route is a documentation route
+ */
+export declare function isDocsRoute(route: string, docsRoute: string): boolean;

package/dist/routing.js

@@ -0,0 +1,92 @@
+/**
+ * Routing utilities for customizable documentation mount points
+ */
+/**
+ * Converts a route slug to a markdown file path
+ * Example: slug="api/overview", docsFolderPath="./docs" -> "./docs/api/overview.md"
+ */
+export function slugToFilePath(slug, docsFolderPath) {
+    const pathParts = Array.isArray(slug) ? slug : slug.split('/').filter(Boolean);
+    const fileName = pathParts.join('/') || 'index';
+    return `${docsFolderPath}/${fileName}.md`;
+}
+/**
+ * Converts a file path to a route URL
+ * Example: filePath="./docs/api/overview.md", docsRoute="/docs" -> "/docs/api/overview"
+ */
+export function filePathToRoute(filePath, docsRoute) {
+    // Remove docs folder prefix and .md extension
+    let relativePath = filePath.replace(/^\.\//, ''); // Remove leading ./
+    relativePath = relativePath.replace(/^docs\//, ''); // Remove docs/ prefix
+    relativePath = relativePath.replace(/\.md$/, ''); // Remove .md extension
+    relativePath = relativePath.replace(/\/index$/, ''); // Remove /index suffix
+    relativePath = relativePath.replace(/^index$/, ''); // Remove index if it's the only part
+    if (relativePath === '' || relativePath === 'index') {
+        return docsRoute || '/docs';
+    }
+    return `${docsRoute || '/docs'}/${relativePath}`;
+}
+/**
+ * Generates a list of all doc routes from a folder structure
+ * This would typically be called at build time to pre-generate routes
+ */
+export function generateDocRoutes(files, docsRoute = '/docs', docsFolderPath = './docs') {
+    return files.map((file) => filePathToRoute(file, docsRoute)).filter((route) => route !== docsRoute || !route.endsWith('/'));
+}
+/**
+ * Validates a docs route
+ */
+export function validateRoute(route) {
+    // Must start with /
+    if (!route.startsWith('/')) {
+        return false;
+    }
+    // Should not have trailing slash (except root)
+    if (route !== '/' && route.endsWith('/')) {
+        return false;
+    }
+    // No double slashes
+    if (route.includes('//')) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Create route configuration from ConfigOptions
+ */
+export function createRouteConfig(config) {
+    return {
+        docsRoute: config.docsRoute || '/docs',
+        docsFolderPath: config.docsFolderPath || './docs',
+        basePath: config.basePath || '/docs',
+    };
+}
+/**
+ * Build a navigation link using the docs route
+ */
+export function buildNavLink(slug, docsRoute = '/docs', absolute = false) {
+    if (slug === '' || slug === 'index') {
+        return docsRoute;
+    }
+    const cleanSlug = slug.replace(/\.md$/, '').replace(/\/index$/, '');
+    const link = `${docsRoute}/${cleanSlug}`.replace(/\/+/g, '/'); // Remove double slashes
+    return link;
+}
+/**
+ * Extract slug from a docs route
+ * Example: "/docs/api/overview" with docsRoute="/docs" -> "api/overview"
+ */
+export function extractSlugFromRoute(fullRoute, docsRoute) {
+    if (fullRoute === docsRoute) {
+        return '';
+    }
+    const pattern = `^${docsRoute.replace(/\//g, '\\/')}\\/`;
+    const regex = new RegExp(pattern);
+    return fullRoute.replace(regex, '');
+}
+/**
+ * Check if a route is a documentation route
+ */
+export function isDocsRoute(route, docsRoute) {
+    return route === docsRoute || route.startsWith(`${docsRoute}/`);
+}