@tiramisu-docs/kit 0.1.0

package/src/highlight.ts

@@ -0,0 +1,110 @@
+import { createHighlighter, type Highlighter } from "shiki"
+import { tiramisuGrammar } from "./tiramisu-grammar.js"
+
+let highlighter: Highlighter | null = null
+
+async function getHighlighter(): Promise<Highlighter> {
+  if (!highlighter) {
+    highlighter = await createHighlighter({
+      themes: ["github-light", "github-dark"],
+      langs: [
+        "typescript",
+        "javascript",
+        "bash",
+        "html",
+        "css",
+        "json",
+        "svelte",
+        "yaml",
+        "markdown",
+        "tsx",
+        "jsx",
+        "shell",
+        tiramisuGrammar,
+      ],
+    })
+  }
+  return highlighter
+}
+
+/**
+ * Post-process compiled Svelte output to add syntax highlighting.
+ *
+ * Finds patterns like:
+ *   const __code_0 = "escaped code"
+ *   <CodeBlock language="typescript" code={__code_0} />
+ *
+ * Replaces the code string with Shiki-highlighted HTML.
+ */
+export async function highlightCodeBlocks(svelte: string): Promise<string> {
+  // Find all CodeBlock usages to map varName -> language
+  const langMap = new Map<string, string>()
+  const codeBlockRegex =
+    /<CodeBlock\s+language="([^"]*)"\s+code=\{(__code_\d+)\}\s*\/>/g
+  let match
+  while ((match = codeBlockRegex.exec(svelte)) !== null) {
+    langMap.set(match[2], match[1])
+  }
+
+  // Find CodeTabs usages to map varName -> language
+  const codeTabsRegex =
+    /<CodeTabs\s[^>]*codes=\{\[([^\]]*)\]\}\s+langMap=\{\[([^\]]*)\]\}\s*\/>/g
+  while ((match = codeTabsRegex.exec(svelte)) !== null) {
+    const vars = match[1].split(/,\s*/).map(s => s.trim())
+    const langs = match[2].split(/,\s*/).map(s => s.replace(/^"|"$/g, ""))
+    for (let i = 0; i < vars.length; i++) {
+      if (vars[i] && langs[i]) langMap.set(vars[i], langs[i])
+    }
+  }
+
+  if (langMap.size === 0) return svelte
+
+  const hl = await getHighlighter()
+  const loadedLangs = hl.getLoadedLanguages()
+
+  // Find and replace each __code_N declaration
+  const codeVarRegex = /const (__code_\d+) = ("(?:[^"\\]|\\.)*")/g
+  let result = svelte
+  const replacements: [string, string][] = []
+
+  while ((match = codeVarRegex.exec(svelte)) !== null) {
+    const varName = match[1]
+    const jsonStr = match[2]
+    const language = langMap.get(varName)
+
+    if (!language) continue
+
+    // Decode the JSON string, then unescape HTML entities to get raw code
+    const escapedHtml: string = JSON.parse(jsonStr)
+    const rawCode = escapedHtml
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+
+    const lang = loadedLangs.includes(language) ? language : "text"
+
+    const highlighted = hl.codeToHtml(rawCode, {
+      lang,
+      themes: { light: "github-light", dark: "github-dark" },
+      defaultColor: false,
+    })
+
+    // Extract just the inner content from shiki's <pre><code>...</code></pre>
+    const innerMatch = highlighted.match(
+      /<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/
+    )
+    const inner = innerMatch ? innerMatch[1] : escapedHtml
+
+    replacements.push([
+      `const ${varName} = ${jsonStr}`,
+      `const ${varName} = ${JSON.stringify(inner)}`,
+    ])
+  }
+
+  for (const [from, to] of replacements) {
+    result = result.replace(from, to)
+  }
+
+  return result
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { defineConfig, resolveConfig } from "./config.js"
+export type { TiramisuDocsConfig, ResolvedConfig, SectionConfig, LocaleConfig, I18nConfig, GitHubConfig, FooterConfig, FooterSocials, InstantOgConfig } from "./config.js"
+export type { SidebarItem, SidebarSubgroup, SidebarEntry, SidebarGroup, VirtualDoc, SearchIndexEntry, ResolvedSection, LocaleData, VirtualModule } from "./types.js"
+export { generateSitemap, generateLlmsTxt, generateLlmsFullTxt, generateSkillMd, buildCanonicalUrl, buildPageJsonLd, buildInstantOgUrl } from "./seo.js"
+export { getOpenLinks, getGitHubEditUrl, getPageUrl } from "./lib/open-links.js"
+export type { OpenLink, OpenLinkOptions } from "./lib/open-links.js"

package/src/lib/components/DocPage.svelte

@@ -0,0 +1,430 @@
+<script lang="ts">
+  import type { DocMeta } from "@tiramisu-docs/core"
+  import type { Snippet } from "svelte"
+  import type { SidebarGroup, SidebarEntry } from "../../types.js"
+  import type { InstantOgConfig } from "../../config.js"
+
+  let {
+    meta,
+    children,
+    slug = undefined,
+    baseUrl = undefined,
+    lastEdited = undefined,
+    headerActions = undefined,
+    sidebar = [],
+    siteName = undefined,
+    instantOg = undefined,
+  }: { meta: DocMeta; children: Snippet; slug?: string; baseUrl?: string; lastEdited?: string; headerActions?: Snippet; sidebar?: SidebarGroup[]; siteName?: string; instantOg?: InstantOgConfig } = $props();
+
+  function findGroup(sidebar: SidebarGroup[], slug: string): string | null {
+    for (const group of sidebar) {
+      for (const entry of group.items) {
+        if (entry.type === "item" && entry.slug === slug) return group.label;
+        if (entry.type === "subgroup") {
+          if (entry.slug === slug) return group.label;
+          for (const child of entry.items) {
+            if (child.type === "item" && child.slug === slug)
+              return entry.label;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  const groupName = $derived(
+    slug && sidebar.length ? findGroup(sidebar, slug) : null,
+  );
+
+  function timeAgo(iso: string): string {
+    const seconds = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
+    if (seconds < 60) return "just now";
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30) return `${days} day${days === 1 ? "" : "s"} ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12) return `${months} month${months === 1 ? "" : "s"} ago`;
+    const years = Math.floor(months / 12);
+    return `${years} year${years === 1 ? "" : "s"} ago`;
+  }
+
+  function formatDate(iso: string): string {
+    return new Date(iso).toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+    });
+  }
+
+  import { buildPageJsonLd, buildCanonicalUrl, buildInstantOgUrl } from "../../seo.js";
+
+  const canonicalUrl = $derived(slug && baseUrl ? buildCanonicalUrl(baseUrl, slug) : null);
+
+  const explicitImage = $derived(
+    meta?.image && baseUrl && !meta.image.startsWith("http")
+      ? `${baseUrl.replace(/\/+$/, "")}${meta.image.startsWith("/") ? "" : "/"}${meta.image}`
+      : meta?.image ?? null
+  );
+
+  const imageUrl = $derived(
+    explicitImage
+      ?? (instantOg && canonicalUrl
+        ? buildInstantOgUrl(canonicalUrl, { siteId: instantOg.siteId, template: instantOg.template, theme: instantOg.theme, accentColor: instantOg.accentColor, gradientBg: instantOg.gradientBg })
+        : null)
+  );
+
+  const jsonLd = $derived(
+    slug && baseUrl
+      ? buildPageJsonLd({
+          title: meta?.title ?? slug,
+          slug,
+          baseUrl,
+          description: meta?.description,
+          lastEdited,
+          siteName,
+          image: imageUrl ?? undefined,
+          author: meta?.author,
+        })
+      : null
+  );
+</script>
+
+<svelte:head>
+  {#if meta?.title}
+    <title>{siteName ? `${meta.title} | ${siteName}` : meta.title}</title>
+    <meta property="og:title" content={meta.title} />
+    <meta name="twitter:title" content={meta.title} />
+  {/if}
+  {#if meta?.description}
+    <meta name="description" content={meta.description} />
+    <meta property="og:description" content={meta.description} />
+    <meta name="twitter:description" content={meta.description} />
+  {/if}
+  {#if siteName}
+    <meta property="og:site_name" content={siteName} />
+  {/if}
+  <meta property="og:type" content="article" />
+  <meta name="twitter:card" content={imageUrl ? "summary_large_image" : "summary"} />
+  {#if imageUrl}
+    <meta property="og:image" content={imageUrl} />
+    <meta name="twitter:image" content={imageUrl} />
+  {/if}
+  {#if canonicalUrl}
+    <link rel="canonical" href={canonicalUrl} />
+    <meta property="og:url" content={canonicalUrl} />
+  {/if}
+  {#if jsonLd}
+    {@html `<script type="application/ld+json">${jsonLd}</script>`}
+  {/if}
+</svelte:head>
+
+<article class="doc-content">
+  {#if meta?.title}
+    <div class="mb-10 border-b pb-8">
+      {#if groupName}
+        <p
+          class="mb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground/70"
+        >
+          {groupName}
+        </p>
+      {/if}
+      <div class="flex items-start justify-between gap-4">
+        <h1
+          class="flex items-center gap-3 text-3xl font-bold tracking-tight text-foreground lg:text-4xl"
+        >
+          {#if meta.icon}
+            <iconify-icon icon={meta.icon.includes(":") ? meta.icon : `lucide:${meta.icon}`} width="32" height="32" class="shrink-0 text-muted-foreground"></iconify-icon>
+          {/if}
+          {meta.title}
+        </h1>
+        {#if headerActions}
+          {@render headerActions()}
+        {/if}
+      </div>
+      {#if meta?.description}
+        <p class="mt-3 text-lg text-muted-foreground">
+          {meta.description}
+        </p>
+      {/if}
+    </div>
+  {/if}
+
+  {#key meta?.title}
+    <div class="doc-body doc-animate">
+      {@render children()}
+    </div>
+  {/key}
+
+  {#if lastEdited || meta?.author}
+    <div class="mt-10 flex items-center gap-2 pt-4 text-sm text-muted-foreground">
+      {#if meta?.author}
+        <span>{meta.author}</span>
+      {/if}
+      {#if meta?.author && lastEdited}
+        <span class="text-border">·</span>
+      {/if}
+      {#if lastEdited}
+        <time
+          datetime={lastEdited}
+          title={formatDate(lastEdited)}
+        >
+          Last edited {timeAgo(lastEdited)}
+        </time>
+      {/if}
+    </div>
+  {/if}
+</article>
+
+<style>
+  .doc-animate {
+    animation: doc-fade-in 0.2s ease-out;
+  }
+
+  @keyframes doc-fade-in {
+    from {
+      opacity: 0;
+      transform: translateY(4px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+  .doc-body :global(h1),
+  .doc-body :global(h2),
+  .doc-body :global(h3),
+  .doc-body :global(h4),
+  .doc-body :global(h5),
+  .doc-body :global(h6) {
+    font-weight: 700;
+    letter-spacing: -0.025em;
+    color: var(--foreground);
+    scroll-margin-top: 4rem;
+  }
+
+  .doc-body :global(h1) {
+    font-size: 2.25rem;
+    line-height: 1.2;
+    margin-top: 3rem;
+    margin-bottom: 1.25rem;
+  }
+
+  .doc-body :global(h2) {
+    font-size: 1.5rem;
+    line-height: 1.33;
+    margin-top: 3rem;
+    margin-bottom: 1rem;
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid var(--border);
+  }
+
+  .doc-body :global(h3) {
+    font-size: 1.25rem;
+    line-height: 1.4;
+    margin-top: 2rem;
+    margin-bottom: 0.75rem;
+  }
+
+  .doc-body :global(h4) {
+    font-size: 1.125rem;
+    margin-top: 1.5rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .doc-body :global(h2),
+  .doc-body :global(h3),
+  .doc-body :global(h4) {
+    position: relative;
+  }
+
+  .doc-body :global(p) {
+    font-size: 1rem;
+    line-height: 1.75;
+    color: var(--foreground);
+    margin-bottom: 1.25rem;
+  }
+
+  .doc-body :global(p a),
+  .doc-body :global(li a),
+  .doc-body :global(td a),
+  .doc-body :global(blockquote a) {
+    font-weight: 500;
+    text-decoration: underline;
+    text-underline-offset: 4px;
+    color: var(--foreground);
+    transition: opacity 0.2s;
+  }
+
+  .doc-body :global(p a:hover),
+  .doc-body :global(li a:hover),
+  .doc-body :global(td a:hover),
+  .doc-body :global(blockquote a:hover) {
+    opacity: 0.8;
+  }
+
+  .doc-body :global(h1 > a),
+  .doc-body :global(h2 > a),
+  .doc-body :global(h3 > a),
+  .doc-body :global(h4 > a) {
+    color: inherit;
+    font-weight: inherit;
+  }
+
+  .doc-body :global(strong) {
+    font-weight: 600;
+    color: var(--foreground);
+  }
+
+  .doc-body :global(code) {
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    font-weight: 500;
+    background: var(--muted);
+    color: var(--foreground);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+  }
+
+  .doc-body :global(pre) {
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    background: oklch(0.975 0 0);
+    color: oklch(0.25 0 0);
+    padding: 1rem 1.25rem;
+    margin: 0;
+    overflow-x: auto;
+  }
+
+  :global(.dark) .doc-body :global(pre) {
+    background: oklch(0.105 0 0);
+    color: oklch(0.87 0 0);
+  }
+
+  /* Shiki dual-theme: use light colors by default, dark in dark mode */
+  .doc-body :global(pre span) {
+    color: var(--shiki-light);
+  }
+
+  :global(.dark) .doc-body :global(pre span) {
+    color: var(--shiki-dark);
+  }
+
+  .doc-body :global(pre code) {
+    background: none;
+    border: none;
+    padding: 0;
+    color: inherit;
+    font-size: inherit;
+  }
+
+  .doc-body :global(ul),
+  .doc-body :global(ol) {
+    padding-left: 1.5rem;
+    margin-bottom: 1.25rem;
+  }
+
+  .doc-body :global(ul) {
+    list-style: disc;
+  }
+
+  .doc-body :global(ol) {
+    list-style: decimal;
+  }
+
+  .doc-body :global(li) {
+    font-size: 1rem;
+    line-height: 1.75;
+    margin-bottom: 0.375rem;
+    color: var(--foreground);
+  }
+
+  .doc-body :global(table) {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 1.5rem 0;
+    font-size: 0.875rem;
+  }
+
+  .doc-body :global(th) {
+    font-weight: 600;
+    text-align: left;
+    padding: 0.75rem 1rem;
+    border-bottom: 2px solid var(--border);
+    color: var(--muted-foreground);
+  }
+
+  .doc-body :global(td) {
+    padding: 0.75rem 1rem;
+    border-bottom: 1px solid var(--border);
+  }
+
+  .doc-body :global(tr:last-child td) {
+    border-bottom: none;
+  }
+
+  .doc-body :global(blockquote) {
+    border-left: 2px solid var(--border);
+    padding-left: 1.5rem;
+    margin: 1.5rem 0;
+    font-style: italic;
+    color: var(--muted-foreground);
+  }
+
+  .doc-body :global(blockquote p) {
+    color: var(--muted-foreground);
+  }
+
+  .doc-body :global(img) {
+    border-radius: var(--radius);
+    border: 1px solid var(--border);
+    margin: 1.5rem 0;
+  }
+
+  .doc-body :global(.cards-grid img) {
+    border: none;
+    margin: 0;
+    border-radius: 0;
+  }
+
+  .doc-body :global(hr) {
+    border: none;
+    border-top: 1px solid var(--border);
+    margin: 2.5rem 0;
+  }
+
+  /* Heading anchor # on hover — uses :global block to avoid scoping pseudo-elements */
+  :global(.doc-body h2 > a::before),
+  :global(.doc-body h3 > a::before),
+  :global(.doc-body h4 > a::before) {
+    content: "#";
+    position: absolute;
+    left: -1.5rem;
+    color: var(--muted-foreground);
+    font-weight: 400;
+    opacity: 0;
+    transition: opacity 0.15s;
+  }
+
+  :global(.doc-body h2:hover > a::before),
+  :global(.doc-body h3:hover > a::before),
+  :global(.doc-body h4:hover > a::before) {
+    opacity: 0.6;
+  }
+
+  .doc-body :global(.external-link) {
+    display: inline-flex;
+    align-items: baseline;
+    gap: 0.2em;
+  }
+
+  .doc-body :global(.external-link-icon) {
+    display: inline;
+    vertical-align: middle;
+    opacity: 0.5;
+    flex-shrink: 0;
+  }
+</style>

package/src/lib/components/DocsLayout.svelte

@@ -0,0 +1,145 @@
+<script lang="ts">
+  import "iconify-icon"
+  import TopBar from "./TopBar.svelte"
+  import Navbar from "./Navbar.svelte"
+  import Sidebar from "./Sidebar.svelte"
+  import TableOfContents from "./TableOfContents.svelte"
+  import SearchDialog from "./SearchDialog.svelte"
+  import PageFooter from "./PageFooter.svelte"
+  import { SheetContent } from "$lib/components/ui/sheet/index.js"
+  import { ScrollArea } from "$lib/components/ui/scroll-area/index.js"
+  import { onMount } from "svelte"
+  import type { ResolvedConfig, LocaleConfig } from "../../config.js"
+  import type { SidebarGroup, SidebarEntry, ResolvedSection } from "../../types.js"
+  import type { Heading } from "@tiramisu-docs/core"
+  import type { Snippet } from "svelte"
+
+  let {
+    config,
+    sidebar,
+    headings,
+    children,
+    sections,
+    locale,
+    locales,
+    showFallbackBanner = false,
+  }: { config: ResolvedConfig; sidebar: SidebarGroup[]; headings: Heading[]; children: Snippet; sections?: ResolvedSection[]; locale?: string; locales?: LocaleConfig[]; showFallbackBanner?: boolean } = $props()
+
+  let searchOpen = $state(false)
+  let mobileOpen = $state(false)
+
+  const hasSections = $derived(sections != null && sections.length > 0)
+
+  function docHref(slug: string): string {
+    const prefix = locale ? `/docs/${locale}` : "/docs"
+    if (slug === "index") return prefix
+    const clean = slug.replace(/\/index$/, "")
+    return `${prefix}/${clean}`
+  }
+
+  onMount(() => {
+    function handleKeydown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault()
+        searchOpen = !searchOpen
+      }
+    }
+    document.addEventListener("keydown", handleKeydown)
+    return () => document.removeEventListener("keydown", handleKeydown)
+  })
+</script>
+
+<div class="min-h-screen bg-background text-foreground">
+  {#if hasSections}
+    <TopBar
+      {config}
+      {sections}
+      {locale}
+      {locales}
+      onSearchClick={() => (searchOpen = true)}
+      onMenuClick={() => (mobileOpen = !mobileOpen)}
+    />
+  {:else}
+    <!-- Legacy mobile navbar -->
+    <Navbar {config} {sidebar} onSearchClick={() => (searchOpen = true)} {locale} />
+  {/if}
+
+  {#if showFallbackBanner}
+    <div class="border-b bg-muted/50 px-4 py-2 text-center text-sm text-muted-foreground">
+      This page is not available in the selected language. Showing the default version.
+    </div>
+  {/if}
+
+  <div class="mx-auto flex max-w-[90rem]">
+    <!-- Sidebar (desktop) -->
+    <aside class="relative hidden w-[15rem] shrink-0 border-r lg:block">
+      <div class="absolute inset-0 bg-card" style="left: -100vw; width: calc(100% + 100vw);"></div>
+      <div class="relative sticky top-0 h-screen" style:top={hasSections ? "6rem" : "0"} style:height={hasSections ? "calc(100vh - 6rem)" : "100vh"}>
+        <Sidebar {config} groups={sidebar} onSearchClick={() => (searchOpen = true)} {hasSections} {locale} {locales} />
+      </div>
+    </aside>
+
+    <!-- Main content area -->
+    <main class="min-w-0 flex-1 px-6 py-10 lg:px-10 xl:px-14">
+      <div class="mx-auto max-w-3xl">
+        {@render children()}
+      </div>
+    </main>
+
+    <!-- Table of contents -->
+    {#if headings?.length}
+      <aside class="hidden w-[13rem] shrink-0 xl:block">
+        <div class="sticky overflow-y-auto overscroll-contain py-10 pr-6" style:top={hasSections ? "6rem" : "0"} style:height={hasSections ? "calc(100vh - 6rem)" : "100vh"}>
+          <TableOfContents {headings} />
+        </div>
+      </aside>
+    {/if}
+  </div>
+
+  <PageFooter {config} />
+</div>
+
+<SearchDialog bind:open={searchOpen} {locale} />
+
+<!-- Mobile sidebar sheet (used when TopBar is active) -->
+{#snippet renderMobileEntries(entries: SidebarEntry[], depth: number)}
+  {#each entries as entry}
+    {#if entry.type === "item"}
+      <a
+        href={docHref(entry.slug)}
+        onclick={() => (mobileOpen = false)}
+        class="block rounded-md py-1.5 text-sm text-muted-foreground hover:text-foreground"
+        style:padding-left="{0.5 + depth * 0.75}rem"
+      >
+        {entry.title}
+      </a>
+    {:else if entry.type === "subgroup"}
+      <div class="mt-2 mb-1">
+        <h5
+          class="text-xs font-semibold uppercase tracking-wider text-muted-foreground/70"
+          style:padding-left="{0.5 + depth * 0.75}rem"
+        >{entry.label}</h5>
+        <div class="mt-0.5 space-y-0.5">
+          {@render renderMobileEntries(entry.items, depth + 1)}
+        </div>
+      </div>
+    {/if}
+  {/each}
+{/snippet}
+
+{#if hasSections}
+  <SheetContent open={mobileOpen} onclose={() => (mobileOpen = false)} side="left">
+    <div class="mt-6">
+      <ScrollArea class="h-[calc(100vh-8rem)]">
+        {#each sidebar as group}
+          <div class="mb-4">
+            <h4 class="mb-1 px-2 text-sm font-semibold text-foreground">{group.label}</h4>
+            <div class="space-y-0.5">
+              {@render renderMobileEntries(group.items, 0)}
+            </div>
+          </div>
+        {/each}
+      </ScrollArea>
+    </div>
+  </SheetContent>
+{/if}