@farming-labs/svelte 0.0.1

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Mdsvex configuration helper for @farming-labs/docs.
+ *
+ * Returns a pre-configured mdsvex options object that handles
+ * frontmatter extraction and syntax highlighting.
+ *
+ * @example
+ * ```js
+ * // svelte.config.js
+ * import { createMdsvexConfig } from "@farming-labs/svelte/config";
+ *
+ * const mdsvexConfig = createMdsvexConfig();
+ *
+ * export default {
+ *   extensions: [".svelte", ".svx"],
+ *   preprocess: [mdsvex(mdsvexConfig)],
+ * };
+ * ```
+ */
+export interface MdsvexConfigOptions {
+    extensions?: string[];
+    highlighter?: unknown;
+}
+export declare function createMdsvexConfig(options?: MdsvexConfigOptions): {
+    extensions: string[];
+    smartypants: {
+        dashes: "oldschool";
+    };
+    layout: undefined;
+};

package/dist/config.js

@@ -0,0 +1,26 @@
+/**
+ * Mdsvex configuration helper for @farming-labs/docs.
+ *
+ * Returns a pre-configured mdsvex options object that handles
+ * frontmatter extraction and syntax highlighting.
+ *
+ * @example
+ * ```js
+ * // svelte.config.js
+ * import { createMdsvexConfig } from "@farming-labs/svelte/config";
+ *
+ * const mdsvexConfig = createMdsvexConfig();
+ *
+ * export default {
+ *   extensions: [".svelte", ".svx"],
+ *   preprocess: [mdsvex(mdsvexConfig)],
+ * };
+ * ```
+ */
+export function createMdsvexConfig(options) {
+    return {
+        extensions: options?.extensions ?? [".svx", ".md"],
+        smartypants: { dashes: "oldschool" },
+        layout: undefined,
+    };
+}

package/dist/content.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Content loading utilities for SvelteKit docs.
+ *
+ * Scans the filesystem for `.md` / `.svx` content files,
+ * extracts frontmatter, and builds a navigation tree compatible
+ * with @farming-labs/docs DocsConfig.
+ */
+export interface PageNode {
+    type: "page";
+    name: string;
+    url: string;
+    icon?: string;
+    description?: string;
+}
+export interface FolderNode {
+    type: "folder";
+    name: string;
+    icon?: string;
+    index?: PageNode;
+    children: NavNode[];
+}
+export type NavNode = PageNode | FolderNode;
+export interface NavTree {
+    name: string;
+    children: NavNode[];
+}
+export interface ContentPage {
+    slug: string;
+    url: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    content: string;
+    rawContent: string;
+}
+/**
+ * Scan a content directory and return all docs pages.
+ * Expects a flat or nested structure of `.md` files:
+ *   content/docs/index.md       → /docs
+ *   content/docs/installation.md → /docs/installation
+ *   content/docs/guides/auth.md  → /docs/guides/auth
+ */
+export declare function loadDocsContent(contentDir: string, entry?: string): ContentPage[];
+/**
+ * Build a navigation tree from a content directory.
+ */
+export declare function loadDocsNavTree(contentDir: string, entry?: string): NavTree;
+/**
+ * Flatten a navigation tree into an ordered list of pages.
+ * Useful for computing previous/next page links.
+ */
+export declare function flattenNavTree(tree: NavTree): PageNode[];

package/dist/content.js

@@ -0,0 +1,158 @@
+/**
+ * Content loading utilities for SvelteKit docs.
+ *
+ * Scans the filesystem for `.md` / `.svx` content files,
+ * extracts frontmatter, and builds a navigation tree compatible
+ * with @farming-labs/docs DocsConfig.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+/**
+ * Scan a content directory and return all docs pages.
+ * Expects a flat or nested structure of `.md` files:
+ *   content/docs/index.md       → /docs
+ *   content/docs/installation.md → /docs/installation
+ *   content/docs/guides/auth.md  → /docs/guides/auth
+ */
+export function loadDocsContent(contentDir, entry = "docs") {
+    const pages = [];
+    const absDir = path.resolve(contentDir);
+    function scan(dir, slugParts) {
+        if (!fs.existsSync(dir))
+            return;
+        const entries = fs.readdirSync(dir).sort();
+        for (const name of entries) {
+            const full = path.join(dir, name);
+            const stat = fs.statSync(full);
+            if (stat.isDirectory()) {
+                scan(full, [...slugParts, name]);
+                continue;
+            }
+            if (!name.endsWith(".md") && !name.endsWith(".mdx") && !name.endsWith(".svx"))
+                continue;
+            const raw = fs.readFileSync(full, "utf-8");
+            const { data, content } = matter(raw);
+            const baseName = name.replace(/\.(md|mdx|svx)$/, "");
+            const isIndex = baseName === "index" || baseName === "page" || baseName === "+page";
+            const slug = isIndex
+                ? slugParts.join("/")
+                : [...slugParts, baseName].join("/");
+            const url = slug ? `/${entry}/${slug}` : `/${entry}`;
+            const title = data.title ??
+                baseName.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+            pages.push({
+                slug,
+                url,
+                title,
+                description: data.description,
+                icon: data.icon,
+                content: stripMarkdown(content),
+                rawContent: content,
+            });
+        }
+    }
+    scan(absDir, []);
+    return pages;
+}
+/**
+ * Build a navigation tree from a content directory.
+ */
+export function loadDocsNavTree(contentDir, entry = "docs") {
+    const absDir = path.resolve(contentDir);
+    const children = [];
+    const indexPath = findIndex(absDir);
+    if (indexPath) {
+        const { data } = matter(fs.readFileSync(indexPath, "utf-8"));
+        children.push({
+            type: "page",
+            name: data.title ?? "Documentation",
+            url: `/${entry}`,
+            icon: data.icon,
+        });
+    }
+    children.push(...scanDir(absDir, [], entry));
+    return { name: "Docs", children };
+}
+function scanDir(dir, slugParts, entry) {
+    if (!fs.existsSync(dir))
+        return [];
+    const nodes = [];
+    const entries = fs.readdirSync(dir).sort();
+    for (const name of entries) {
+        const full = path.join(dir, name);
+        if (!fs.statSync(full).isDirectory())
+            continue;
+        const indexPath = findIndex(full);
+        if (!indexPath)
+            continue;
+        const { data } = matter(fs.readFileSync(indexPath, "utf-8"));
+        const slug = [...slugParts, name];
+        const url = `/${entry}/${slug.join("/")}`;
+        const displayName = data.title ?? name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        const icon = data.icon;
+        const childDirs = fs.readdirSync(full).filter((n) => {
+            const p = path.join(full, n);
+            return fs.statSync(p).isDirectory() && findIndex(p) !== null;
+        });
+        if (childDirs.length > 0) {
+            nodes.push({
+                type: "folder",
+                name: displayName,
+                icon,
+                index: { type: "page", name: displayName, url, icon },
+                children: scanDir(full, slug, entry),
+            });
+        }
+        else {
+            nodes.push({ type: "page", name: displayName, url, icon });
+        }
+    }
+    return nodes;
+}
+function findIndex(dir) {
+    for (const name of ["page.md", "page.mdx", "index.md", "index.svx", "+page.md", "+page.svx"]) {
+        const p = path.join(dir, name);
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Flatten a navigation tree into an ordered list of pages.
+ * Useful for computing previous/next page links.
+ */
+export function flattenNavTree(tree) {
+    const pages = [];
+    function walk(nodes) {
+        for (const node of nodes) {
+            if (node.type === "page") {
+                pages.push(node);
+            }
+            else if (node.type === "folder") {
+                if (node.index)
+                    pages.push(node.index);
+                walk(node.children);
+            }
+        }
+    }
+    walk(tree.children);
+    return pages;
+}
+function stripMarkdown(content) {
+    return content
+        .replace(/^(import|export)\s.*$/gm, "")
+        .replace(/<[^>]+\/>/g, "")
+        .replace(/<\/?[A-Z][^>]*>/g, "")
+        .replace(/<\/?[a-z][^>]*>/g, "")
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2")
+        .replace(/```[\s\S]*?```/g, "")
+        .replace(/`([^`]+)`/g, "$1")
+        .replace(/^>\s+/gm, "")
+        .replace(/^[-*_]{3,}\s*$/gm, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @farming-labs/svelte
+ *
+ * SvelteKit adapter for the @farming-labs/docs framework.
+ * Provides content loading, navigation tree building, search,
+ * and server-side markdown rendering for SvelteKit-based documentation sites.
+ */
+export { loadDocsContent, loadDocsNavTree, flattenNavTree, type NavNode, type NavTree, type PageNode, type FolderNode } from "./content.js";
+export { createMdsvexConfig } from "./config.js";
+export { renderMarkdown } from "./markdown.js";
+export { createDocsServer, type DocsServer } from "./server.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @farming-labs/svelte
+ *
+ * SvelteKit adapter for the @farming-labs/docs framework.
+ * Provides content loading, navigation tree building, search,
+ * and server-side markdown rendering for SvelteKit-based documentation sites.
+ */
+export { loadDocsContent, loadDocsNavTree, flattenNavTree } from "./content.js";
+export { createMdsvexConfig } from "./config.js";
+export { renderMarkdown } from "./markdown.js";
+export { createDocsServer } from "./server.js";

package/dist/markdown.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Server-side markdown rendering with Shiki syntax highlighting.
+ *
+ * Converts raw markdown content to HTML, supporting:
+ *   - Fenced code blocks with dual-theme syntax highlighting
+ *   - Copy-to-clipboard buttons on code blocks
+ *   - Tabbed code blocks (`<Tabs>` / `<Tab>` syntax)
+ *   - Callouts / admonitions (GitHub `[!NOTE]` and `**Note:**` styles)
+ *   - Tables, lists, inline formatting, headings with anchor IDs
+ */
+/**
+ * Render a markdown string to HTML with full syntax highlighting,
+ * callouts, tables, tabs, and copy-to-clipboard support.
+ *
+ * Designed for server-side use in SvelteKit `+page.server` loaders.
+ */
+export declare function renderMarkdown(content: string): Promise<string>;

package/dist/markdown.js

@@ -0,0 +1,280 @@
+/**
+ * Server-side markdown rendering with Shiki syntax highlighting.
+ *
+ * Converts raw markdown content to HTML, supporting:
+ *   - Fenced code blocks with dual-theme syntax highlighting
+ *   - Copy-to-clipboard buttons on code blocks
+ *   - Tabbed code blocks (`<Tabs>` / `<Tab>` syntax)
+ *   - Callouts / admonitions (GitHub `[!NOTE]` and `**Note:**` styles)
+ *   - Tables, lists, inline formatting, headings with anchor IDs
+ */
+import { createHighlighter } from "shiki";
+let highlighterPromise;
+function getHighlighter() {
+    if (!highlighterPromise) {
+        highlighterPromise = createHighlighter({
+            themes: ["github-light", "github-dark"],
+            langs: [
+                "javascript",
+                "typescript",
+                "jsx",
+                "tsx",
+                "json",
+                "bash",
+                "shellscript",
+                "html",
+                "css",
+                "markdown",
+                "yaml",
+                "sql",
+                "python",
+                "dotenv",
+            ],
+        });
+    }
+    return highlighterPromise;
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/<[^>]+>/g, "")
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .trim();
+}
+const calloutIcons = {
+    note: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>',
+    warning: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
+    tip: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 18h6"/><path d="M10 22h4"/><path d="M15.09 14c.18-.98.65-1.74 1.41-2.5A4.65 4.65 0 0018 8 6 6 0 006 8c0 1 .23 2.23 1.5 3.5A4.61 4.61 0 019 14"/></svg>',
+    important: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z"/></svg>',
+    caution: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>',
+};
+function renderCallout(type, content) {
+    const icon = calloutIcons[type] || calloutIcons.note;
+    const label = type.charAt(0).toUpperCase() + type.slice(1);
+    return `<div class="fd-callout fd-callout-${type}" role="note"><div class="fd-callout-indicator" role="none"></div><div class="fd-callout-icon">${icon}</div><div class="fd-callout-content"><p class="fd-callout-title">${label}</p><p>${content}</p></div></div>`;
+}
+function highlightCode(hl, code, lang) {
+    if (lang === "sh" || lang === "shell")
+        lang = "bash";
+    if (lang === "env")
+        lang = "dotenv";
+    const supported = hl.getLoadedLanguages();
+    if (!supported.includes(lang))
+        lang = "text";
+    const trimmedCode = code.replace(/\n$/, "");
+    try {
+        return {
+            html: hl.codeToHtml(trimmedCode, {
+                lang,
+                themes: { light: "github-light", dark: "github-dark" },
+            }),
+            raw: trimmedCode,
+        };
+    }
+    catch {
+        const escaped = trimmedCode
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+        return {
+            html: `<pre class="shiki"><code>${escaped}</code></pre>`,
+            raw: trimmedCode,
+        };
+    }
+}
+function parseMeta(meta) {
+    const lang = (meta.split(/\s/)[0] || "text").toLowerCase();
+    const titleMatch = meta.match(/title=["']([^"']+)["']/);
+    return { lang, title: titleMatch ? titleMatch[1] : null };
+}
+function wrapCodeWithCopy(html, rawCode, title) {
+    const escapedRaw = rawCode
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+    const copyBtn = `<button class="fd-copy-btn" data-code="${escapedRaw}" title="Copy code"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1"/></svg></button>`;
+    if (title) {
+        return `<div class="fd-codeblock fd-codeblock--titled"><div class="fd-codeblock-title"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/></svg><span class="fd-codeblock-title-text">${title}</span>${copyBtn}</div><div class="fd-codeblock-content">${html}</div></div>`;
+    }
+    return `<div class="fd-codeblock">${copyBtn}<div class="fd-codeblock-content">${html}</div></div>`;
+}
+function dedentCode(raw) {
+    const lines = raw.replace(/\n$/, "").split("\n");
+    const indent = lines.reduce((min, l) => {
+        if (!l.trim())
+            return min;
+        const spaces = l.match(/^(\s*)/)?.[1].length ?? 0;
+        return Math.min(min, spaces);
+    }, Infinity);
+    if (indent > 0 && indent < Infinity) {
+        return lines.map((l) => l.slice(indent)).join("\n");
+    }
+    return raw;
+}
+/**
+ * Render a markdown string to HTML with full syntax highlighting,
+ * callouts, tables, tabs, and copy-to-clipboard support.
+ *
+ * Designed for server-side use in SvelteKit `+page.server` loaders.
+ */
+export async function renderMarkdown(content) {
+    if (!content)
+        return "";
+    const hl = await getHighlighter();
+    let result = content;
+    // ── Tabs blocks: <Tabs items={[...]}> ... </Tabs> ──
+    const tabsBlocks = [];
+    result = result.replace(/<Tabs\s+items=\{?\[([^\]]+)\]\}?>([\s\S]*?)<\/Tabs>/g, (_, itemsStr, body) => {
+        const items = itemsStr
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""));
+        const panels = [];
+        const tabRegex = /<Tab\s+value=["']([^"']+)["']>([\s\S]*?)<\/Tab>/g;
+        let tabMatch;
+        while ((tabMatch = tabRegex.exec(body)) !== null) {
+            const tabValue = tabMatch[1];
+            const tabContent = tabMatch[2].trim();
+            const codeMatch = tabContent.match(/```([^\n]*)\n([\s\S]*?)```/);
+            if (codeMatch) {
+                const { lang, title } = parseMeta(codeMatch[1]);
+                const dedented = dedentCode(codeMatch[2]);
+                const { html, raw } = highlightCode(hl, dedented, lang);
+                panels.push({ value: tabValue, html: wrapCodeWithCopy(html, raw, title) });
+            }
+            else {
+                panels.push({ value: tabValue, html: `<p>${tabContent}</p>` });
+            }
+        }
+        let tabsHtml = `<div class="fd-tabs" data-tabs>`;
+        tabsHtml += `<div class="fd-tabs-list" role="tablist">`;
+        for (let i = 0; i < items.length; i++) {
+            tabsHtml += `<button role="tab" class="fd-tab-trigger${i === 0 ? " fd-tab-active" : ""}" data-tab-value="${items[i]}" aria-selected="${i === 0}">${items[i]}</button>`;
+        }
+        tabsHtml += `</div>`;
+        for (let i = 0; i < panels.length; i++) {
+            tabsHtml += `<div class="fd-tab-panel${i === 0 ? " fd-tab-panel-active" : ""}" data-tab-panel="${panels[i].value}" role="tabpanel">${panels[i].html}</div>`;
+        }
+        tabsHtml += `</div>`;
+        const placeholder = `%%TABS_${tabsBlocks.length}%%`;
+        tabsBlocks.push(tabsHtml);
+        return placeholder;
+    });
+    // ── Fenced code blocks ──
+    const codeBlocks = [];
+    result = result.replace(/```([^\n]*)\n([\s\S]*?)```/g, (_, meta, code) => {
+        const { lang, title } = parseMeta(meta);
+        const { html, raw } = highlightCode(hl, code, lang);
+        const placeholder = `%%CODEBLOCK_${codeBlocks.length}%%`;
+        codeBlocks.push(wrapCodeWithCopy(html, raw, title));
+        return placeholder;
+    });
+    // Inline code
+    result = result.replace(/`([^`]+)`/g, "<code>$1</code>");
+    // Headings (h4 → h1 order to avoid prefix collisions)
+    result = result.replace(/^#### (.+)$/gm, (_, text) => {
+        return `<h4 id="${slugify(text)}">${text}</h4>`;
+    });
+    result = result.replace(/^### (.+)$/gm, (_, text) => {
+        return `<h3 id="${slugify(text)}">${text}</h3>`;
+    });
+    result = result.replace(/^## (.+)$/gm, (_, text) => {
+        return `<h2 id="${slugify(text)}">${text}</h2>`;
+    });
+    result = result.replace(/^# (.+)$/gm, "<h1>$1</h1>");
+    // ── Callouts / blockquotes (before inline formatting) ──
+    const calloutBlocks = [];
+    result = result.replace(/(?:^>\s*.+\n?)+/gm, (block) => {
+        const lines = block.split("\n").filter(Boolean);
+        const inner = lines.map((l) => l.replace(/^>\s?/, "")).join("\n");
+        const ghMatch = inner.match(/^\[!(NOTE|WARNING|TIP|IMPORTANT|CAUTION)\]\s*\n?([\s\S]*)/i);
+        if (ghMatch) {
+            const type = ghMatch[1].toLowerCase();
+            const calloutContent = ghMatch[2].trim();
+            const placeholder = `%%CALLOUT_${calloutBlocks.length}%%`;
+            calloutBlocks.push(renderCallout(type, calloutContent));
+            return placeholder;
+        }
+        const boldMatch = inner.match(/^\*\*(Note|Warning|Tip|Important|Caution):\*\*\s*([\s\S]*)/i);
+        if (boldMatch) {
+            const type = boldMatch[1].toLowerCase();
+            const calloutContent = boldMatch[2].trim();
+            const placeholder = `%%CALLOUT_${calloutBlocks.length}%%`;
+            calloutBlocks.push(renderCallout(type, calloutContent));
+            return placeholder;
+        }
+        return `<blockquote><p>${inner}</p></blockquote>`;
+    });
+    // Inline formatting
+    result = result.replace(/\*\*\*(.+?)\*\*\*/g, "<strong><em>$1</em></strong>");
+    result = result.replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>");
+    result = result.replace(/\*(.+?)\*/g, "<em>$1</em>");
+    // Links
+    result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+    // Horizontal rules
+    result = result.replace(/^---$/gm, "<hr />");
+    // Tables
+    result = result.replace(/^\|(.+)\|\n\|[-| ]+\|\n((?:\|.+\|\n?)+)/gm, (_, headerRow, bodyRows) => {
+        const headers = headerRow
+            .split("|")
+            .map((h) => h.trim())
+            .filter(Boolean);
+        const rows = bodyRows
+            .trim()
+            .split("\n")
+            .map((row) => row
+            .split("|")
+            .map((c) => c.trim())
+            .filter(Boolean));
+        const headerHtml = headers.map((h) => `<th>${h}</th>`).join("");
+        const rowsHtml = rows
+            .map((row) => `<tr>${row.map((c) => `<td>${c}</td>`).join("")}</tr>`)
+            .join("");
+        return `<div class="fd-table-wrapper"><table><thead><tr>${headerHtml}</tr></thead><tbody>${rowsHtml}</tbody></table></div>`;
+    });
+    // Unordered lists
+    result = result.replace(/(?:^- .+\n?)+/gm, (block) => {
+        const items = block
+            .split("\n")
+            .filter((l) => l.startsWith("- "))
+            .map((l) => `<li>${l.slice(2)}</li>`)
+            .join("");
+        return `<ul>${items}</ul>`;
+    });
+    // Ordered lists
+    result = result.replace(/(?:^\d+\. .+\n?)+/gm, (block) => {
+        const items = block
+            .split("\n")
+            .filter((l) => /^\d+\. /.test(l))
+            .map((l) => `<li>${l.replace(/^\d+\. /, "")}</li>`)
+            .join("");
+        return `<ol>${items}</ol>`;
+    });
+    // Wrap remaining bare text in <p> tags
+    result = result
+        .split("\n\n")
+        .map((block) => {
+        block = block.trim();
+        if (!block)
+            return "";
+        if (/^<(h[1-6]|pre|ul|ol|blockquote|hr|table|div)/.test(block))
+            return block;
+        if (/^%%(CODEBLOCK|CALLOUT|TABS)_\d+%%$/.test(block))
+            return block;
+        return `<p>${block}</p>`;
+    })
+        .join("\n");
+    // Restore placeholders
+    for (let i = 0; i < codeBlocks.length; i++) {
+        result = result.replace(`%%CODEBLOCK_${i}%%`, codeBlocks[i]);
+    }
+    for (let i = 0; i < calloutBlocks.length; i++) {
+        result = result.replace(`%%CALLOUT_${i}%%`, calloutBlocks[i]);
+    }
+    for (let i = 0; i < tabsBlocks.length; i++) {
+        result = result.replace(`%%TABS_${i}%%`, tabsBlocks[i]);
+    }
+    return result;
+}

package/dist/server.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Server-side helpers for SvelteKit docs routes.
+ *
+ * `createDocsServer(config)` returns all the load functions and
+ * handlers needed for a complete docs site.  Each route file becomes
+ * a one-line re-export.
+ *
+ * @example
+ * ```ts
+ * // src/lib/docs.server.ts
+ * import { createDocsServer } from "@farming-labs/svelte/server";
+ * import config from "../../docs.config.js";
+ *
+ * export const { load, GET, POST } = createDocsServer(config);
+ * ```
+ *
+ * ```ts
+ * // routes/docs/+layout.server.js
+ * export { load } from "$lib/docs.server";
+ * ```
+ */
+import { loadDocsNavTree } from "./content.js";
+import type { PageNode } from "./content.js";
+interface UnifiedLoadEvent {
+    url: URL;
+}
+interface RequestEvent {
+    url: URL;
+    request: Request;
+}
+export interface DocsServer {
+    load: (event: UnifiedLoadEvent) => Promise<{
+        tree: ReturnType<typeof loadDocsNavTree>;
+        flatPages: PageNode[];
+        title: string;
+        description?: string;
+        html: string;
+        slug?: string;
+        previousPage: PageNode | null;
+        nextPage: PageNode | null;
+        editOnGithub?: string;
+        lastModified: string;
+    }>;
+    GET: (event: RequestEvent) => Response;
+    POST: (event: RequestEvent) => Promise<Response>;
+}
+/**
+ * Create all server-side functions needed for a SvelteKit docs site.
+ *
+ * @param config - The `DocsConfig` object (from `defineDocs()` in `docs.config.ts`).
+ */
+export declare function createDocsServer(config?: Record<string, any>): DocsServer;
+export {};

package/dist/server.js

@@ -0,0 +1,250 @@
+/**
+ * Server-side helpers for SvelteKit docs routes.
+ *
+ * `createDocsServer(config)` returns all the load functions and
+ * handlers needed for a complete docs site.  Each route file becomes
+ * a one-line re-export.
+ *
+ * @example
+ * ```ts
+ * // src/lib/docs.server.ts
+ * import { createDocsServer } from "@farming-labs/svelte/server";
+ * import config from "../../docs.config.js";
+ *
+ * export const { load, GET, POST } = createDocsServer(config);
+ * ```
+ *
+ * ```ts
+ * // routes/docs/+layout.server.js
+ * export { load } from "$lib/docs.server";
+ * ```
+ */
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { loadDocsNavTree, loadDocsContent, flattenNavTree } from "./content.js";
+import { renderMarkdown } from "./markdown.js";
+/**
+ * Create all server-side functions needed for a SvelteKit docs site.
+ *
+ * @param config - The `DocsConfig` object (from `defineDocs()` in `docs.config.ts`).
+ */
+export function createDocsServer(config = {}) {
+    const entry = config.entry ?? "docs";
+    const githubRaw = config.github;
+    const github = typeof githubRaw === "string"
+        ? { url: githubRaw }
+        : githubRaw ?? null;
+    const githubRepo = github?.url;
+    const githubBranch = github?.branch ?? "main";
+    const githubContentPath = github?.directory;
+    const contentDir = path.resolve(config.contentDir ?? entry);
+    const aiConfig = config.ai ?? {};
+    // Allow top-level apiKey as a shorthand
+    if (config.apiKey && !aiConfig.apiKey) {
+        aiConfig.apiKey = config.apiKey;
+    }
+    // ─── Unified load (tree + page content in one call) ────────
+    async function load(event) {
+        const tree = loadDocsNavTree(contentDir, entry);
+        const flatPages = flattenNavTree(tree);
+        const prefix = new RegExp(`^/${entry}/?`);
+        const slug = event.url.pathname.replace(prefix, "");
+        const isIndex = slug === "";
+        let filePath = null;
+        let relPath = "";
+        if (isIndex) {
+            for (const name of ["page.md", "page.mdx", "index.md"]) {
+                const candidate = path.join(contentDir, name);
+                if (fs.existsSync(candidate)) {
+                    filePath = candidate;
+                    relPath = name;
+                    break;
+                }
+            }
+        }
+        else {
+            const candidates = [
+                path.join(contentDir, slug, "page.md"),
+                path.join(contentDir, slug, "page.mdx"),
+                path.join(contentDir, slug, "index.md"),
+                path.join(contentDir, slug, "index.svx"),
+                path.join(contentDir, `${slug}.md`),
+                path.join(contentDir, `${slug}.svx`),
+            ];
+            for (const candidate of candidates) {
+                if (fs.existsSync(candidate)) {
+                    filePath = candidate;
+                    relPath = path.relative(contentDir, candidate);
+                    break;
+                }
+            }
+        }
+        if (!filePath) {
+            const err = new Error(`Page not found: /${entry}/${slug}`);
+            err.status = 404;
+            throw err;
+        }
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const { data, content } = matter(raw);
+        const html = await renderMarkdown(content);
+        const currentUrl = isIndex ? `/${entry}` : `/${entry}/${slug}`;
+        const currentIndex = flatPages.findIndex((p) => p.url === currentUrl);
+        const previousPage = currentIndex > 0 ? flatPages[currentIndex - 1] : null;
+        const nextPage = currentIndex < flatPages.length - 1 ? flatPages[currentIndex + 1] : null;
+        let editOnGithub;
+        if (githubRepo && githubContentPath) {
+            editOnGithub = `${githubRepo}/blob/${githubBranch}/${githubContentPath}/${relPath}`;
+        }
+        const stat = fs.statSync(filePath);
+        const lastModified = stat.mtime.toLocaleDateString("en-US", {
+            year: "numeric",
+            month: "long",
+            day: "numeric",
+        });
+        const fallbackTitle = isIndex
+            ? "Documentation"
+            : slug.split("/").pop()?.replace(/-/g, " ") ?? "Documentation";
+        return {
+            tree,
+            flatPages,
+            title: data.title ?? fallbackTitle,
+            description: data.description,
+            html,
+            ...(isIndex ? {} : { slug }),
+            previousPage,
+            nextPage,
+            editOnGithub,
+            lastModified,
+        };
+    }
+    // ─── Search index ──────────────────────────────────────────
+    let searchIndex = null;
+    function getSearchIndex() {
+        if (!searchIndex) {
+            searchIndex = loadDocsContent(contentDir, entry);
+        }
+        return searchIndex;
+    }
+    function searchByQuery(query) {
+        const index = getSearchIndex();
+        return index
+            .map((page) => {
+            const titleMatch = page.title.toLowerCase().includes(query) ? 10 : 0;
+            const words = query.split(/\s+/);
+            const contentMatch = words.reduce((score, word) => {
+                return score + (page.content.toLowerCase().includes(word) ? 1 : 0);
+            }, 0);
+            return { ...page, score: titleMatch + contentMatch };
+        })
+            .filter((r) => r.score > 0)
+            .sort((a, b) => b.score - a.score);
+    }
+    // ─── GET /api/docs?query=… — full-text search ────────────
+    function GET(event) {
+        const query = event.url.searchParams.get("query")?.toLowerCase().trim();
+        if (!query) {
+            return new Response(JSON.stringify([]), {
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const results = searchByQuery(query)
+            .slice(0, 10)
+            .map(({ title, url, description }) => ({
+            content: title,
+            url,
+            description,
+        }));
+        return new Response(JSON.stringify(results), {
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    // ─── POST /api/docs — AI chat with RAG ────────────────────
+    const projectName = (typeof config.nav?.title === "string"
+        ? config.nav.title
+        : null);
+    const packageName = aiConfig.packageName;
+    const docsUrl = aiConfig.docsUrl;
+    function buildDefaultSystemPrompt() {
+        const lines = [
+            `You are a helpful documentation assistant${projectName ? ` for ${projectName}` : ""}.`,
+            "Answer questions based on the provided documentation context.",
+            "Be concise and accurate. If the answer is not in the context, say so honestly.",
+            "Use markdown formatting for code examples and links.",
+        ];
+        if (packageName) {
+            lines.push(`When showing import examples, always use "${packageName}" as the package name.`);
+        }
+        if (docsUrl) {
+            lines.push(`When linking to documentation pages, use "${docsUrl}" as the base URL (e.g. ${docsUrl}/docs/get-started).`);
+        }
+        return lines.join(" ");
+    }
+    const DEFAULT_SYSTEM_PROMPT = buildDefaultSystemPrompt();
+    async function POST(event) {
+        if (!aiConfig.enabled) {
+            return new Response(JSON.stringify({
+                error: "AI is not enabled. Set `ai: { enabled: true }` in your docs config to enable it.",
+            }), { status: 404, headers: { "Content-Type": "application/json" } });
+        }
+        const resolvedKey = aiConfig.apiKey ??
+            (typeof process !== "undefined" ? process.env?.OPENAI_API_KEY : undefined);
+        if (!resolvedKey) {
+            return new Response(JSON.stringify({
+                error: "AI is enabled but no API key was found. Set `apiKey` in your docs config `ai` section or add OPENAI_API_KEY to your environment.",
+            }), { status: 500, headers: { "Content-Type": "application/json" } });
+        }
+        let body;
+        try {
+            body = await event.request.json();
+        }
+        catch {
+            return new Response(JSON.stringify({ error: "Invalid JSON body. Expected { messages: [...] }" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const messages = body.messages;
+        if (!Array.isArray(messages) || messages.length === 0) {
+            return new Response(JSON.stringify({ error: "messages array is required and must not be empty." }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
+        if (!lastUserMessage) {
+            return new Response(JSON.stringify({ error: "At least one user message is required." }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const maxResults = aiConfig.maxResults ?? 5;
+        const scored = searchByQuery(lastUserMessage.content.toLowerCase()).slice(0, maxResults);
+        const contextParts = scored.map((doc) => `## ${doc.title}\nURL: ${doc.url}\n${doc.description ? `Description: ${doc.description}\n` : ""}\n${doc.content}`);
+        const context = contextParts.join("\n\n---\n\n");
+        const systemPrompt = aiConfig.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+        const systemMessage = {
+            role: "system",
+            content: context
+                ? `${systemPrompt}\n\n---\n\nDocumentation context:\n\n${context}`
+                : systemPrompt,
+        };
+        const llmMessages = [
+            systemMessage,
+            ...messages.filter((m) => m.role !== "system"),
+        ];
+        const baseUrl = (aiConfig.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+        const model = aiConfig.model ?? "gpt-4o-mini";
+        const llmResponse = await fetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${resolvedKey}`,
+            },
+            body: JSON.stringify({ model, stream: true, messages: llmMessages }),
+        });
+        if (!llmResponse.ok) {
+            const errText = await llmResponse.text().catch(() => "Unknown error");
+            return new Response(JSON.stringify({ error: `LLM API error (${llmResponse.status}): ${errText}` }), { status: 502, headers: { "Content-Type": "application/json" } });
+        }
+        return new Response(llmResponse.body, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            },
+        });
+    }
+    return { load, GET, POST };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@farming-labs/svelte",
+  "version": "0.0.1",
+  "description": "SvelteKit adapter for @farming-labs/docs — content loading and navigation utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./content": {
+      "types": "./dist/content.d.ts",
+      "import": "./dist/content.js",
+      "default": "./dist/content.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "import": "./dist/markdown.js",
+      "default": "./dist/markdown.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "docs",
+    "svelte",
+    "sveltekit",
+    "documentation"
+  ],
+  "author": "Farming Labs",
+  "license": "MIT",
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "shiki": "^3.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.3",
+    "@farming-labs/docs": "0.0.2-beta.4"
+  },
+  "peerDependencies": {
+    "@farming-labs/docs": "*"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}