@tiramisu-docs/kit 0.1.0

package/dist/vite.js

@@ -0,0 +1,406 @@
+import { compileTiramisu } from "@tiramisu-docs/core";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { highlightCodeBlocks } from "./highlight.js";
+import { findTiramisuFiles, extractPlainText, titleCase } from "./scan.js";
+/** Wrap compileTiramisu to produce Vite-friendly errors with file location */
+function compileWithLocation(source, filePath) {
+    const dir = path.dirname(filePath);
+    try {
+        return compileTiramisu(source, {
+            resolveFile(src) {
+                const resolved = path.resolve(dir, src);
+                return fs.readFileSync(resolved, "utf-8");
+            },
+        });
+    }
+    catch (err) {
+        const isParseError = err instanceof Error && "line" in err;
+        if (isParseError) {
+            const parseErr = err;
+            const enhanced = new Error(parseErr.hint ?? parseErr.message);
+            Object.assign(enhanced, {
+                id: filePath,
+                loc: { file: filePath, line: parseErr.line, column: parseErr.column ?? 0 },
+                plugin: "tiramisu-docs",
+            });
+            if (parseErr.stack)
+                enhanced.stack = parseErr.stack;
+            throw enhanced;
+        }
+        throw err;
+    }
+}
+function resolveLastEdited(filePath, meta) {
+    if (meta.lastEdited)
+        return new Date(meta.lastEdited).toISOString();
+    try {
+        const stdout = execSync(`git log -1 --format=%cI "${filePath}"`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (stdout)
+            return new Date(stdout).toISOString();
+    }
+    catch { }
+    return fs.statSync(filePath).mtime.toISOString();
+}
+const VIRTUAL_MODULE_ID = "virtual:tiramisu-docs";
+const RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+const TIRAMISU_SVELTE_SUFFIX = ".tiramisu.svelte";
+export function buildSidebarTree(docs, groupOrder = []) {
+    const groupMap = new Map();
+    function getOrCreateGroup(label) {
+        // Normalize lookup: case-insensitive match against existing groups
+        for (const [key, group] of groupMap) {
+            if (key.toLowerCase() === label.toLowerCase()) {
+                return group;
+            }
+        }
+        const group = { label, items: [] };
+        groupMap.set(label, group);
+        return group;
+    }
+    function getOrCreateSubgroup(parent, segment) {
+        const key = segment.toLowerCase();
+        const existing = parent.find((e) => e.type === "subgroup" && e.key === key);
+        if (existing)
+            return existing;
+        const sub = {
+            type: "subgroup",
+            key,
+            label: titleCase(segment),
+            items: [],
+            order: 999,
+        };
+        parent.push(sub);
+        return sub;
+    }
+    for (const doc of docs) {
+        const segments = doc.slug.split("/");
+        const item = {
+            type: "item",
+            title: doc.meta.title ?? doc.slug,
+            slug: doc.slug,
+            order: doc.meta.order ?? 999,
+            icon: doc.meta.icon,
+        };
+        if (segments.length === 1) {
+            // Root-level file: use meta.group
+            const groupLabel = doc.meta.group ?? "Docs";
+            const group = getOrCreateGroup(groupLabel);
+            group.items.push(item);
+        }
+        else {
+            // Nested file: first segment = group (static heading), deeper segments = subgroups
+            const groupLabel = titleCase(segments[0]);
+            const group = getOrCreateGroup(groupLabel);
+            const fileName = segments[segments.length - 1];
+            // Walk/create subgroups for middle segments (starting at segments[1])
+            let parent = group.items;
+            let lastSub = null;
+            for (let i = 1; i < segments.length - 1; i++) {
+                const sub = getOrCreateSubgroup(parent, segments[i]);
+                lastSub = sub;
+                parent = sub.items;
+            }
+            if (fileName === "index" && lastSub) {
+                // Deeper folder index → sets subgroup slug/label
+                lastSub.slug = item.slug;
+                if (item.order < lastSub.order)
+                    lastSub.order = item.order;
+                if (item.title !== item.slug)
+                    lastSub.label = item.title;
+                if (doc.meta.icon)
+                    lastSub.icon = doc.meta.icon;
+            }
+            else if (fileName === "index" && !lastSub) {
+                // Top-level folder index (e.g. "integrations/index") → sets group label only
+                if (item.title !== item.slug) {
+                    group.label = item.title;
+                }
+                if (doc.meta.icon)
+                    group.icon = doc.meta.icon;
+            }
+            else {
+                parent.push(item);
+            }
+        }
+    }
+    // Sort entries recursively
+    function sortEntries(entries) {
+        for (const entry of entries) {
+            if (entry.type === "subgroup") {
+                sortEntries(entry.items);
+                // Derive subgroup order from its index page, or min child order
+                if (!entry.slug) {
+                    const minOrder = entry.items.reduce((min, e) => {
+                        const o = e.order;
+                        return o < min ? o : min;
+                    }, entry.order);
+                    entry.order = minOrder;
+                }
+            }
+        }
+        entries.sort((a, b) => {
+            const ao = a.type === "item" ? a.order : a.order;
+            const bo = b.type === "item" ? b.order : b.order;
+            return ao - bo;
+        });
+    }
+    const sidebar = [];
+    for (const [, group] of groupMap) {
+        sortEntries(group.items);
+        sidebar.push({ label: group.label, items: group.items, icon: group.icon });
+    }
+    // Sort groups by groupOrder config
+    if (groupOrder.length > 0) {
+        sidebar.sort((a, b) => {
+            const ai = groupOrder.indexOf(a.label);
+            const bi = groupOrder.indexOf(b.label);
+            const ao = ai === -1 ? Infinity : ai;
+            const bo = bi === -1 ? Infinity : bi;
+            return ao - bo;
+        });
+    }
+    return sidebar;
+}
+export function buildSectionSidebars(docs, sections, implicitLabel) {
+    const allSectionPaths = flattenSectionPaths(sections);
+    const rootDocs = docs.filter((d) => !allSectionPaths.some((p) => d.slug === p || d.slug.startsWith(p + "/")));
+    const result = [];
+    if (rootDocs.length > 0) {
+        result.push({
+            label: implicitLabel ?? "Docs",
+            sidebar: buildSidebarTree(rootDocs),
+        });
+    }
+    for (const section of sections) {
+        result.push(resolveSection(docs, section));
+    }
+    return result;
+}
+function flattenSectionPaths(sections) {
+    const paths = [];
+    for (const s of sections) {
+        if (s.path)
+            paths.push(s.path);
+        if (s.children)
+            paths.push(...flattenSectionPaths(s.children));
+    }
+    return paths;
+}
+function resolveSection(docs, section) {
+    if (section.href) {
+        return { label: section.label, href: section.href, icon: section.icon };
+    }
+    if (section.children) {
+        return {
+            label: section.label,
+            icon: section.icon,
+            children: section.children.map((c) => resolveSection(docs, c)),
+        };
+    }
+    const sectionDocs = docs
+        .filter((d) => d.slug === section.path || d.slug.startsWith(section.path + "/"));
+    const sidebar = buildSidebarTree(sectionDocs);
+    return {
+        label: section.label,
+        path: section.path,
+        icon: section.icon,
+        sidebar,
+    };
+}
+export function buildLocaleData(allDocs, locales) {
+    const result = {};
+    for (const locale of locales) {
+        const prefix = locale.code + "/";
+        const docs = allDocs
+            .filter((d) => d.slug.startsWith(prefix))
+            .map((d) => ({ slug: d.slug.slice(prefix.length), meta: d.meta, headings: d.headings, lastEdited: d.lastEdited }));
+        result[locale.code] = { docs };
+    }
+    return result;
+}
+export function tiramisuPlugin(options = {}) {
+    const docsDir = options.docsDir ?? "src/docs";
+    const config = options.config;
+    const groupOrder = config?.sidebar?.groupOrder ?? [];
+    let viteRoot = process.cwd();
+    function resolveDocsDir() {
+        return path.resolve(viteRoot, docsDir);
+    }
+    function buildVirtualModule() {
+        const absDocsDir = resolveDocsDir();
+        const files = findTiramisuFiles(absDocsDir);
+        const docs = [];
+        for (const file of files) {
+            const source = fs.readFileSync(file, "utf-8");
+            const { meta, headings } = compileWithLocation(source, file);
+            const relativePath = path.relative(absDocsDir, file);
+            const slug = relativePath.replace(/\.tiramisu$/, "").replace(/\\/g, "/");
+            const lastEdited = resolveLastEdited(file, meta);
+            docs.push({ slug, meta, headings, lastEdited });
+        }
+        // Build search index with hierarchical group paths
+        function resolveSearchGroup(slug, meta) {
+            const segments = slug.split("/");
+            if (segments.length === 1)
+                return meta.group ?? "Docs";
+            return segments
+                .slice(0, -1)
+                .map(titleCase)
+                .join(" > ");
+        }
+        const searchIndex = docs.map((doc) => {
+            const file = path.resolve(absDocsDir, doc.slug + ".tiramisu");
+            const source = fs.readFileSync(file, "utf-8");
+            const { svelte } = compileWithLocation(source, file);
+            const text = extractPlainText(svelte);
+            return {
+                id: doc.slug,
+                title: doc.meta.title ?? doc.slug,
+                group: resolveSearchGroup(doc.slug, doc.meta),
+                slug: doc.slug,
+                headings: doc.headings.map((h) => h.text).join(" "),
+                text,
+            };
+        });
+        // Build dynamic imports — use .tiramisu.svelte suffix so resolveId maps them
+        const importsEntries = docs
+            .map((doc) => {
+            const absPath = path
+                .resolve(absDocsDir, doc.slug + ".tiramisu")
+                .replace(/\\/g, "/");
+            return `  "${doc.slug}": () => import("${absPath}")`;
+        })
+            .join(",\n");
+        if (config?.i18n) {
+            const localeData = buildLocaleData(docs, config.i18n.locales);
+            const localeBlocks = config.i18n.locales.map((locale) => {
+                const localeDocs = localeData[locale.code].docs;
+                const localeSections = config.sections
+                    ? buildSectionSidebars(localeDocs, config.sections, config.title)
+                    : undefined;
+                const localeSidebar = buildSidebarTree(localeDocs, groupOrder);
+                // Build locale-specific search index
+                const localeSearchIndex = localeDocs.map((doc) => {
+                    const fullSlug = `${locale.code}/${doc.slug}`;
+                    const file = path.resolve(absDocsDir, fullSlug + ".tiramisu");
+                    const source = fs.readFileSync(file, "utf-8");
+                    const { svelte } = compileWithLocation(source, file);
+                    const text = extractPlainText(svelte);
+                    return {
+                        id: doc.slug,
+                        title: doc.meta.title ?? doc.slug,
+                        group: resolveSearchGroup(doc.slug, doc.meta),
+                        slug: doc.slug,
+                        headings: docs.find(d => d.slug === fullSlug)?.headings?.map(h => h.text).join(" ") ?? "",
+                        text,
+                    };
+                });
+                const localeImports = localeDocs
+                    .map((doc) => {
+                    const fullSlug = `${locale.code}/${doc.slug}`;
+                    const absPath = path.resolve(absDocsDir, fullSlug + ".tiramisu").replace(/\\/g, "/");
+                    return `    "${doc.slug}": () => import("${absPath}")`;
+                })
+                    .join(",\n");
+                return `  "${locale.code}": {
+    sections: ${JSON.stringify(localeSections, null, 2)},
+    sidebar: ${JSON.stringify(localeSidebar, null, 2)},
+    docs: ${JSON.stringify(localeDocs, null, 2)},
+    searchIndex: ${JSON.stringify(localeSearchIndex)},
+    docImports: {\n${localeImports}\n    },
+  }`;
+            }).join(",\n");
+            return [
+                `export const locales = {\n${localeBlocks}\n};`,
+                `export const defaultLocale = "${config.i18n.defaultLocale}";`,
+                `export const sidebar = locales["${config.i18n.defaultLocale}"].sidebar;`,
+                `export const sections = locales["${config.i18n.defaultLocale}"].sections;`,
+                `export const docs = locales["${config.i18n.defaultLocale}"].docs;`,
+                `export const searchIndex = locales["${config.i18n.defaultLocale}"].searchIndex;`,
+                `export const docImports = locales["${config.i18n.defaultLocale}"].docImports;`,
+            ].join("\n\n");
+        }
+        if (config?.sections) {
+            const resolvedSections = buildSectionSidebars(docs, config.sections, config.title);
+            return [
+                `export const locales = undefined;`,
+                `export const defaultLocale = undefined;`,
+                `export const sections = ${JSON.stringify(resolvedSections, null, 2)};`,
+                `export const sidebar = [];`,
+                `export const docs = ${JSON.stringify(docs, null, 2)};`,
+                `export const searchIndex = ${JSON.stringify(searchIndex)};`,
+                `export const docImports = {\n${importsEntries}\n};`,
+            ].join("\n\n");
+        }
+        else {
+            const sidebar = buildSidebarTree(docs, groupOrder);
+            return [
+                `export const locales = undefined;`,
+                `export const defaultLocale = undefined;`,
+                `export const sections = undefined;`,
+                `export const sidebar = ${JSON.stringify(sidebar, null, 2)};`,
+                `export const docs = ${JSON.stringify(docs, null, 2)};`,
+                `export const searchIndex = ${JSON.stringify(searchIndex)};`,
+                `export const docImports = {\n${importsEntries}\n};`,
+            ].join("\n\n");
+        }
+    }
+    return {
+        name: "tiramisu-docs",
+        enforce: "pre",
+        configResolved(config) {
+            viteRoot = config.root;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_MODULE_ID) {
+                return RESOLVED_VIRTUAL_MODULE_ID;
+            }
+            // Resolve .tiramisu imports to a virtual .svelte ID
+            // so the Svelte plugin processes the output
+            if (id.endsWith(".tiramisu")) {
+                const resolved = path.isAbsolute(id) ? id : path.resolve(viteRoot, id);
+                if (fs.existsSync(resolved)) {
+                    return resolved + ".svelte";
+                }
+            }
+            return undefined;
+        },
+        async load(id) {
+            if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                return buildVirtualModule();
+            }
+            // Compile .tiramisu files to Svelte component source
+            // These come in as .tiramisu.svelte due to resolveId above
+            if (id.endsWith(TIRAMISU_SVELTE_SUFFIX)) {
+                const tiramisuPath = id.slice(0, -".svelte".length);
+                if (!fs.existsSync(tiramisuPath))
+                    return undefined;
+                const source = fs.readFileSync(tiramisuPath, "utf-8");
+                const { svelte } = compileWithLocation(source, tiramisuPath);
+                return await highlightCodeBlocks(svelte);
+            }
+            return undefined;
+        },
+        handleHotUpdate(ctx) {
+            if (ctx.file.endsWith(".tiramisu")) {
+                // Invalidate the virtual module so sidebar/docs get rebuilt
+                const virtualMod = ctx.server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
+                if (virtualMod) {
+                    ctx.server.moduleGraph.invalidateModule(virtualMod);
+                }
+                // Invalidate the compiled .svelte version too
+                const svelteMod = ctx.server.moduleGraph.getModuleById(ctx.file + ".svelte");
+                if (svelteMod) {
+                    ctx.server.moduleGraph.invalidateModule(svelteMod);
+                }
+                ctx.server.ws.send({ type: "full-reload" });
+                return [];
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@tiramisu-docs/kit",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "svelte": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./seo": {
+      "types": "./dist/seo.d.ts",
+      "default": "./dist/seo.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    },
+    "./components/*": {
+      "svelte": "./src/lib/components/*",
+      "default": "./src/lib/components/*"
+    },
+    "./styles/*": {
+      "default": "./src/lib/styles/*"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./utils": {
+      "types": "./src/lib/utils.ts",
+      "default": "./src/lib/utils.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "bun run build",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@timeleap/tiramisu": "^1.9.0",
+    "@tiramisu-docs/core": "workspace:*",
+    "clsx": "^2.1.1",
+    "iconify-icon": "^2.3.0",
+    "minisearch": "^7.2.0",
+    "katex": "^0.16.21",
+    "mermaid": "^11.6.0",
+    "shiki": "^4.0.1",
+    "tailwind-merge": "^3.5.0"
+  },
+  "peerDependencies": {
+    "@sveltejs/kit": "^2.0.0",
+    "svelte": "^5.0.0",
+    "vite": ">=6.0.0"
+  },
+  "devDependencies": {
+    "@internationalized/date": "^3.10.0",
+    "@sveltejs/kit": "^2.53.4",
+    "@types/node": "^20.12.11",
+    "svelte": "^5.0.0",
+    "tailwind-variants": "^3.2.2",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.4.5",
+    "vite": "^7.3.1"
+  }
+}

package/src/config.ts

@@ -0,0 +1,133 @@
+export interface LogoConfig {
+  light: string
+  dark: string
+}
+
+export interface SectionConfig {
+  label: string
+  path?: string
+  href?: string
+  icon?: string
+  children?: SectionConfig[]
+}
+
+export interface LocaleConfig {
+  code: string
+  label: string
+  flag?: string
+}
+
+export interface I18nConfig {
+  defaultLocale: string
+  locales: LocaleConfig[]
+  fallback?: "default-language" | "404"
+}
+
+export interface ResolvedI18nConfig {
+  defaultLocale: string
+  locales: LocaleConfig[]
+  fallback: "default-language" | "404"
+}
+
+export interface GitHubConfig {
+  repo: string
+  branch?: string
+  dir?: string
+}
+
+export interface FooterSocials {
+  github?: string
+  x?: string
+  discord?: string
+  bluesky?: string
+  mastodon?: string
+  youtube?: string
+  linkedin?: string
+}
+
+export interface FooterConfig {
+  socials?: FooterSocials
+  copyright?: string
+}
+
+export interface InstantOgConfig {
+  siteId: string
+  template?: string
+  theme?: "light" | "dark"
+  accentColor?: string
+  gradientBg?: boolean
+}
+
+export interface TiramisuDocsConfig {
+  title?: string
+  description?: string
+  url?: string
+  logo?: string | LogoConfig
+  nav?: { label: string; href: string }[]
+  sidebar?: {
+    groupOrder?: string[]
+  }
+  sections?: SectionConfig[]
+  i18n?: I18nConfig
+  github?: GitHubConfig
+  mcp?: boolean | string
+  footer?: FooterConfig
+  instantOg?: InstantOgConfig
+  theme?: {
+    primary?: string
+    radius?: string
+  }
+}
+
+export interface ResolvedConfig {
+  title: string
+  description: string
+  url?: string
+  logo: LogoConfig
+  nav: { label: string; href: string }[]
+  sections?: SectionConfig[]
+  i18n?: ResolvedI18nConfig
+  github?: GitHubConfig
+  mcp?: boolean | string
+  footer?: FooterConfig
+  instantOg?: InstantOgConfig
+  sidebar: { groupOrder: string[] }
+  theme: { primary: string; radius: string }
+}
+
+export function defineConfig(config: TiramisuDocsConfig): TiramisuDocsConfig {
+  return config
+}
+
+function resolveLogo(logo?: string | LogoConfig): LogoConfig {
+  if (!logo) return { light: "", dark: "" }
+  if (typeof logo === "string") return { light: logo, dark: logo }
+  return logo
+}
+
+export function resolveConfig(config: TiramisuDocsConfig): ResolvedConfig {
+  return {
+    title: config.title ?? "Documentation",
+    description: config.description ?? "",
+    url: config.url?.replace(/\/+$/, ""),
+    logo: resolveLogo(config.logo),
+    nav: config.nav ?? [],
+    sections: config.sections,
+    github: config.github,
+    mcp: config.mcp,
+    footer: config.footer,
+    instantOg: config.instantOg,
+    i18n: config.i18n ? {
+      defaultLocale: config.i18n.defaultLocale,
+      locales: config.i18n.locales,
+      fallback: config.i18n.fallback ?? "default-language",
+    } : undefined,
+    sidebar: {
+      groupOrder: config.sidebar?.groupOrder ?? [],
+    },
+    theme: {
+      primary: config.theme?.primary ?? "hsl(262, 83%, 58%)",
+      radius: config.theme?.radius ?? "0.5rem",
+    },
+  }
+}