@aravindc26/velu 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/schema/velu.schema.json

@@ -10,6 +10,69 @@
       "type": "string",
       "description": "Path or URL to the JSON schema for editor validation."
     },
+    "theme": {
+      "type": "string",
+      "description": "Named theme preset that controls the overall look and feel.",
+      "enum": ["violet", "maple", "palm", "willow", "linden", "almond", "aspen"],
+      "default": "violet"
+    },
+    "colors": {
+      "type": "object",
+      "description": "Override the theme's accent colors.",
+      "properties": {
+        "primary": {
+          "type": "string",
+          "description": "Primary brand color (hex). Used as accent in both light and dark modes unless overridden.",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "light": {
+          "type": "string",
+          "description": "Accent color for light mode (hex). Overrides primary in light mode.",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "dark": {
+          "type": "string",
+          "description": "Accent color for dark mode (hex). Overrides primary in dark mode.",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "appearance": {
+      "type": "string",
+      "description": "Controls light/dark mode behavior.",
+      "enum": ["system", "light", "dark"],
+      "default": "system"
+    },
+    "styling": {
+      "type": "object",
+      "description": "Fine-grained styling options.",
+      "properties": {
+        "codeblocks": {
+          "type": "object",
+          "description": "Code block styling options.",
+          "properties": {
+            "theme": {
+              "description": "Shiki theme for syntax highlighting. Use a string for a single theme, or an object with light/dark keys.",
+              "oneOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "light": { "type": "string" },
+                    "dark": { "type": "string" }
+                  },
+                  "required": ["light", "dark"],
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "navigation": {
       "type": "object",
       "description": "Defines the site navigation hierarchy: tabs → groups → pages.",

package/src/build.ts

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, rmSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
+import { generateThemeCss, type ThemeConfig, type VeluColors, type VeluStyling } from "./themes.js";
 
 // ── Types (used only by build.ts for page copying) ─────────────────────────────
 
@@ -17,6 +18,10 @@ interface VeluTab {
 
 interface VeluConfig {
   $schema?: string;
+  theme?: string;
+  colors?: VeluColors;
+  appearance?: "system" | "light" | "dark";
+  styling?: VeluStyling;
   navigation: {
     tabs?: VeluTab[];
     groups?: VeluGroup[];
@@ -132,6 +137,10 @@ export interface VeluTab {
 
 export interface VeluConfig {
   $schema?: string;
+  theme?: string;
+  colors?: { primary?: string; light?: string; dark?: string };
+  appearance?: 'system' | 'light' | 'dark';
+  styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
     tabs?: VeluTab[];
     groups?: VeluGroup[];
@@ -296,9 +305,31 @@ export function getTabSidebarMap(): Record<string, string[]> {
   writeFileSync(join(outDir, "src", "lib", "velu.ts"), veluLib, "utf-8");
   console.log("📚 Generated config module");
 
-  // ── 4. Generate site config ────────────────────────────────────────────────
+  // ── 4. Generate theme CSS ─────────────────────────────────────────────────
+  const themeCss = generateThemeCss({
+    theme: config.theme,
+    colors: config.colors,
+    appearance: config.appearance,
+    styling: config.styling,
+  });
+  writeFileSync(join(outDir, "src", "styles", "velu-theme.css"), themeCss, "utf-8");
+  console.log(`🎨 Generated theme: ${config.theme || "mint"}`);
+
+  // ── 5. Generate site config ────────────────────────────────────────────────
+  // Build expressiveCode config for code block themes
+  let expressiveCodeConfig = "";
+  if (config.styling?.codeblocks?.theme) {
+    const cbt = config.styling.codeblocks.theme;
+    if (typeof cbt === "string") {
+      expressiveCodeConfig = `\n      expressiveCode: { themes: ['${cbt}'] },`;
+    } else {
+      expressiveCodeConfig = `\n      expressiveCode: { themes: ['${cbt.dark}', '${cbt.light}'] },`;
+    }
+  }
+
   const astroConfig = `import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import { ion } from 'starlight-ion-theme';
 import { getSidebar } from './src/lib/velu.ts';
 
 export default defineConfig({
@@ -306,11 +337,12 @@ export default defineConfig({
   integrations: [
     starlight({
       title: 'Velu Docs',
+      plugins: [ion()],
       components: {
-        Header: './src/components/Header.astro',
         Sidebar: './src/components/Sidebar.astro',
+        PageTitle: './src/components/PageTitle.astro',
       },
-      customCss: ['./src/styles/tabs.css'],
+      customCss: ['./src/styles/velu-theme.css', './src/styles/tabs.css'],${expressiveCodeConfig}
       sidebar: getSidebar(),
     }),
   ],
@@ -319,64 +351,26 @@ export default defineConfig({
   writeFileSync(join(outDir, "_config.mjs"), astroConfig, "utf-8");
   console.log("⚙️  Generated site config");
 
-  // ── 5. Generate Header.astro — reads tabs from velu.ts ────────────────────
-  const headerComponent = `---
-import Default from '@astrojs/starlight/components/Header.astro';
-import { getTabs } from '../lib/velu.ts';
+  // ── 6. Generate Sidebar.astro — tabs at top + filtered content ─────────────
+  const sidebarComponent = `---
+import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
+import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
+import { getTabs, getTabSidebarMap } from '../lib/velu.ts';
 
 const tabs = getTabs();
+const tabSidebarMap = getTabSidebarMap();
 const currentPath = Astro.url.pathname;
 
 function isTabActive(tab: any, path: string): boolean {
   if (tab.href) return false;
   if (tab.pathPrefix === '__default__') {
     const otherPrefixes = tabs
-      .filter((t) => t.pathPrefix && t.pathPrefix !== '__default__' && !t.href)
-      .map((t) => t.pathPrefix);
-    return !otherPrefixes.some((p) => path.startsWith('/' + p + '/'));
+      .filter((t: any) => t.pathPrefix && t.pathPrefix !== '__default__' && !t.href)
+      .map((t: any) => t.pathPrefix);
+    return !otherPrefixes.some((p: string) => path.startsWith('/' + p + '/'));
   }
   return path.startsWith('/' + tab.pathPrefix + '/');
 }
----
-
-<Default {...Astro.props}>
-  <slot />
-</Default>
-
-<nav class="velu-tabs">
-  <div class="velu-tabs-inner">
-    {tabs.map((tab) => {
-      if (tab.href) {
-        return (
-          <a href={tab.href} class="velu-tab" target="_blank" rel="noopener noreferrer">
-            {tab.label}
-            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7 17L17 7M17 7H7M17 7V17"/></svg>
-          </a>
-        );
-      }
-      const active = isTabActive(tab, currentPath);
-      const href = tab.firstPage ? '/' + tab.firstPage + '/' : '/';
-      return (
-        <a href={href} class:list={['velu-tab', { active }]}>
-          {tab.label}
-        </a>
-      );
-    })}
-  </div>
-</nav>
-`;
-  writeFileSync(join(outDir, "src", "components", "Header.astro"), headerComponent, "utf-8");
-  console.log("🧩 Generated header component");
-
-  // ── 6. Generate Sidebar.astro — reads filter map from velu.ts ─────────────
-  const sidebarComponent = `---
-import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
-import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
-import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
-import { getTabSidebarMap } from '../lib/velu.ts';
-
-const tabSidebarMap = getTabSidebarMap();
-const currentPath = Astro.url.pathname;
 
 function getActivePrefix(path: string): string {
   const prefixes = Object.keys(tabSidebarMap).filter(p => p !== '__default__');
@@ -396,9 +390,29 @@ const filteredSidebar = sidebar.filter((entry: any) => {
 });
 ---
 
-<SidebarPersister>
-  <SidebarSublist sublist={filteredSidebar} />
-</SidebarPersister>
+<div class="velu-sidebar-tabs">
+  {tabs.map((tab) => {
+    if (tab.href) {
+      return (
+        <a href={tab.href} class="velu-sidebar-tab" target="_blank" rel="noopener noreferrer">
+          {tab.icon && <span class="velu-sidebar-tab-icon" data-icon={tab.icon} />}
+          <span>{tab.label}</span>
+          <svg class="velu-external-icon" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7 17L17 7M17 7H7M17 7V17"/></svg>
+        </a>
+      );
+    }
+    const active = isTabActive(tab, currentPath);
+    const href = tab.firstPage ? '/' + tab.firstPage + '/' : '/';
+    return (
+      <a href={href} class:list={['velu-sidebar-tab', { active }]}>
+        {tab.icon && <span class="velu-sidebar-tab-icon" data-icon={tab.icon} />}
+        <span>{tab.label}</span>
+      </a>
+    );
+  })}
+</div>
+
+<SidebarSublist sublist={filteredSidebar} />
 
 <div class="md:sl-hidden">
   <MobileMenuFooter />
@@ -407,75 +421,291 @@ const filteredSidebar = sidebar.filter((entry: any) => {
   writeFileSync(join(outDir, "src", "components", "Sidebar.astro"), sidebarComponent, "utf-8");
   console.log("📋 Generated sidebar component");
 
-  // ── 7. Generate tabs.css ──────────────────────────────────────────────────
-  const tabsCss = `/* ── Velu layout overrides ──────────────────────────────────────────────── */
+  // ── 7. Generate PageTitle.astro — title row with copy page button ────────
+  const pageTitleComponent = `---
+const currentUrl = Astro.url.href;
+const title = Astro.locals.starlightRoute.entry.data.title;
+---
+
+<div class="velu-title-row">
+  <h1 id="_top">{title}</h1>
+  <div class="velu-copy-page-container">
+    <div class="velu-copy-split-btn">
+      <button class="velu-copy-main-btn" data-action="direct-copy">
+        <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 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+        <span class="velu-copy-label">Copy page</span>
+      </button>
+      <span class="velu-copy-sep"></span>
+      <button class="velu-copy-caret-btn" aria-expanded="false" aria-haspopup="true">
+        <svg class="velu-copy-chevron" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
+      </button>
+    </div>
+    <div class="velu-copy-dropdown" hidden>
+      <button class="velu-copy-option" data-action="copy">
+        <svg width="18" height="18" 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 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+        <div>
+          <div class="velu-copy-option-title">Copy page</div>
+          <div class="velu-copy-option-desc">Copy page as Markdown for LLMs</div>
+        </div>
+      </button>
+      <a class="velu-copy-option" href={\`https://chatgpt.com/?prompt=Read+from+\${encodeURIComponent(currentUrl)}+so+I+can+ask+questions+about+it.\`} target="_blank" rel="noopener noreferrer">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M22.282 9.821a5.985 5.985 0 0 0-.516-4.91 6.046 6.046 0 0 0-6.51-2.9A6.065 6.065 0 0 0 4.981 4.18a5.985 5.985 0 0 0-3.998 2.9 6.046 6.046 0 0 0 .743 7.097 5.98 5.98 0 0 0 .51 4.911 6.051 6.051 0 0 0 6.515 2.9A5.985 5.985 0 0 0 13.26 24a6.056 6.056 0 0 0 5.772-4.206 5.99 5.99 0 0 0 3.997-2.9 6.056 6.056 0 0 0-.747-7.073zM13.26 22.43a4.476 4.476 0 0 1-2.876-1.04l.141-.081 4.779-2.758a.795.795 0 0 0 .392-.681v-6.737l2.02 1.168a.071.071 0 0 1 .038.052v5.583a4.504 4.504 0 0 1-4.494 4.494zM3.6 18.304a4.47 4.47 0 0 1-.535-3.014l.142.085 4.783 2.759a.771.771 0 0 0 .78 0l5.843-3.369v2.332a.08.08 0 0 1-.033.062L9.74 19.95a4.5 4.5 0 0 1-6.14-1.646zM2.34 7.896a4.485 4.485 0 0 1 2.366-1.973V11.6a.766.766 0 0 0 .388.676l5.815 3.355-2.02 1.168a.076.076 0 0 1-.071 0l-4.83-2.786A4.504 4.504 0 0 1 2.34 7.872zm16.597 3.855l-5.833-3.387L15.119 7.2a.076.076 0 0 1 .071 0l4.83 2.791a4.494 4.494 0 0 1-.676 8.105v-5.678a.79.79 0 0 0-.407-.667zm2.01-3.023l-.141-.085-4.774-2.782a.776.776 0 0 0-.785 0L9.409 9.23V6.897a.066.066 0 0 1 .028-.061l4.83-2.787a4.5 4.5 0 0 1 6.68 4.66zm-12.64 4.135l-2.02-1.164a.08.08 0 0 1-.038-.057V6.075a4.5 4.5 0 0 1 7.375-3.453l-.142.08L8.704 5.46a.795.795 0 0 0-.393.681zm1.097-2.365l2.602-1.5 2.607 1.5v2.999l-2.597 1.5-2.607-1.5z"/></svg>
+        <div>
+          <div class="velu-copy-option-title">Open in ChatGPT <span class="velu-external-arrow">&nearr;</span></div>
+          <div class="velu-copy-option-desc">Ask questions about this page</div>
+        </div>
+      </a>
+      <a class="velu-copy-option" href={\`https://claude.ai/new?q=Read+from+\${encodeURIComponent(currentUrl)}+so+I+can+ask+questions+about+it.\`} target="_blank" rel="noopener noreferrer">
+        <svg width="18" height="18" viewBox="0 0 200 200" style="overflow:visible" fill="currentColor"><path d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"/></svg>
+        <div>
+          <div class="velu-copy-option-title">Open in Claude <span class="velu-external-arrow">&nearr;</span></div>
+          <div class="velu-copy-option-desc">Ask questions about this page</div>
+        </div>
+      </a>
+    </div>
+  </div>
+</div>
+
+<script is:inline>
+  (function init() {
+    var caretBtn = document.querySelector('.velu-copy-caret-btn');
+    var mainBtn = document.querySelector('.velu-copy-main-btn');
+    var dropdown = document.querySelector('.velu-copy-dropdown');
+    var label = document.querySelector('.velu-copy-label');
+    if (!caretBtn || !mainBtn || !dropdown) return;
+
+    function doCopy() {
+      if (label) label.textContent = 'Copying...';
+      var titleEl = document.querySelector('#_top');
+      var article = document.querySelector('.sl-markdown-content') || document.querySelector('.content-panel') || document.querySelector('main');
+      var text = '';
+      if (titleEl) text = '# ' + titleEl.textContent + '\\n\\n';
+      if (article) text += article.innerText;
+      if (text) {
+        navigator.clipboard.writeText(text).then(function() {
+          if (label) label.textContent = 'Copied!';
+          setTimeout(function() { if (label) label.textContent = 'Copy page'; }, 1500);
+        });
+      }
+      dropdown.hidden = true;
+      caretBtn.setAttribute('aria-expanded', 'false');
+    }
+
+    mainBtn.onclick = function(e) { e.stopPropagation(); doCopy(); };
+
+    caretBtn.onclick = function(e) {
+      e.stopPropagation();
+      var open = dropdown.hidden;
+      dropdown.hidden = !open;
+      caretBtn.setAttribute('aria-expanded', String(open));
+    };
+
+    document.addEventListener('click', function() {
+      dropdown.hidden = true;
+      caretBtn.setAttribute('aria-expanded', 'false');
+    });
+
+    dropdown.onclick = function(e) { e.stopPropagation(); };
+
+    var copyOpt = dropdown.querySelector('[data-action="copy"]');
+    if (copyOpt) {
+      copyOpt.onclick = function() { doCopy(); };
+    }
+  })();
+</script>
+`;
+  writeFileSync(join(outDir, "src", "components", "PageTitle.astro"), pageTitleComponent, "utf-8");
+  console.log("📋 Generated page title component");
+
+  // ── 8. Generate tabs.css ──────────────────────────────────────────────────
+  const tabsCss = `/* ── Velu sidebar tabs ─────────────────────────────────────────────────── */
 
 :root {
-  --sl-nav-height: 6rem;
+  --sl-sidebar-width: 16rem;
 }
 
-/* Fixed header: flex column, no bottom padding — tab bar sits at the bottom */
-.page > header.header {
+.velu-sidebar-tabs {
   display: flex;
   flex-direction: column;
-  padding-bottom: 0;
+  gap: 0.15rem;
+  padding: 0.35rem;
+  margin-bottom: 1rem;
+  background-color: var(--sl-color-bg);
+  border: 1px solid var(--sl-color-gray-5);
+  border-radius: 0.5rem;
+}
+
+.velu-sidebar-tab {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.45rem 0.65rem;
+  font-size: var(--sl-text-sm);
+  font-weight: 600;
+  color: var(--sl-color-gray-3);
+  text-decoration: none;
+  border-radius: 0.375rem;
+  transition: color 0.15s, background-color 0.15s;
+}
+
+.velu-sidebar-tab:hover {
+  color: var(--sl-color-white);
+  background-color: var(--sl-color-gray-6);
 }
 
-/* Standard nav content fills the top */
-.page > header.header > .header.sl-flex {
-  height: auto;
-  flex: 1;
+.velu-sidebar-tab.active {
+  color: var(--sl-color-white);
+  background-color: var(--sl-color-gray-6);
 }
 
-/* ── Tab bar ───────────────────────────────────────────────────────────── */
+:root[data-theme='light'] .velu-sidebar-tab.active {
+  color: var(--sl-color-white);
+  background-color: var(--sl-color-gray-7);
+}
 
-.velu-tabs {
+.velu-external-icon {
+  opacity: 0.4;
   flex-shrink: 0;
-  /* Stretch to full header width past its padding */
-  margin-inline: calc(-1 * var(--sl-nav-pad-x));
-  padding-inline: var(--sl-nav-pad-x);
-  background: var(--sl-color-bg-nav);
+  margin-inline-start: auto;
 }
 
-.velu-tabs-inner {
+/* ── Copy page button ─────────────────────────────────────────────────── */
+
+.velu-title-row {
   display: flex;
-  gap: 0.25rem;
-  overflow-x: auto;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.velu-title-row h1 {
+  margin: 0;
 }
 
-.velu-tab {
+.velu-copy-page-container {
+  position: relative;
+  flex-shrink: 0;
+  margin-top: 0.35rem;
+}
+
+.velu-copy-split-btn {
   display: inline-flex;
   align-items: center;
-  gap: 0.35rem;
-  padding: 0.55rem 0.85rem;
-  font-size: var(--sl-text-sm);
+  border: 1px solid var(--sl-color-gray-5);
+  border-radius: 999px;
+  background: var(--sl-color-bg-nav);
+}
+
+.velu-copy-main-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.35rem 0.5rem 0.35rem 0.75rem;
+  font-size: var(--sl-text-xs);
   font-weight: 500;
   color: var(--sl-color-gray-3);
+  background: none;
+  border: none;
+  cursor: pointer;
+  transition: color 0.15s;
+}
+
+.velu-copy-main-btn:hover {
+  color: var(--sl-color-white);
+}
+
+.velu-copy-sep {
+  width: 1px;
+  height: 14px;
+  background-color: var(--sl-color-gray-5);
+  flex-shrink: 0;
+}
+
+.velu-copy-caret-btn {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.35rem 0.5rem;
+  background: none;
+  border: none;
+  color: var(--sl-color-gray-3);
+  cursor: pointer;
+  transition: color 0.15s;
+}
+
+.velu-copy-caret-btn:hover {
+  color: var(--sl-color-white);
+}
+
+.velu-copy-chevron {
+  transition: transform 0.15s;
+}
+
+.velu-copy-caret-btn[aria-expanded='true'] .velu-copy-chevron {
+  transform: rotate(180deg);
+}
+
+.velu-copy-dropdown {
+  position: absolute;
+  right: 0;
+  top: calc(100% + 0.35rem);
+  z-index: 100;
+  min-width: 16rem;
+  padding: 0.35rem;
+  background: var(--sl-color-bg-nav);
+  border: 1px solid var(--sl-color-gray-5);
+  border-radius: 0.5rem;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+}
+
+.velu-copy-option {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 0.5rem 0.6rem;
+  font: inherit;
+  font-size: var(--sl-text-sm);
+  color: var(--sl-color-gray-2);
+  text-align: left;
   text-decoration: none;
-  border-radius: 0.375rem;
-  transition: color 0.15s, background-color 0.15s;
-  white-space: nowrap;
+  background: none;
+  border: none;
+  border-radius: 0.35rem;
+  cursor: pointer;
+  transition: background-color 0.15s;
 }
 
-.velu-tab:hover {
-  color: var(--sl-color-gray-1);
+.velu-copy-option:hover {
   background-color: var(--sl-color-gray-6);
 }
 
-.velu-tab.active {
-  color: var(--sl-color-white);
-  background-color: var(--sl-color-gray-5);
+.velu-copy-option svg {
+  flex-shrink: 0;
+  opacity: 0.7;
+  margin-top: 0.15rem;
+  overflow: visible;
 }
 
-.velu-tab svg {
+.velu-copy-option-title {
+  font-weight: 500;
+  line-height: 1.3;
+}
+
+.velu-copy-option-desc {
+  font-size: var(--sl-text-xs);
+  color: var(--sl-color-gray-3);
+  line-height: 1.3;
+}
+
+.velu-external-arrow {
+  font-size: 0.75em;
   opacity: 0.5;
-  flex-shrink: 0;
 }
 `;
   writeFileSync(join(outDir, "src", "styles", "tabs.css"), tabsCss, "utf-8");
   console.log("🎨 Generated tabs.css");
 
-  // ── 8. Static boilerplate ─────────────────────────────────────────────────
+  // ── 9. Static boilerplate ─────────────────────────────────────────────────
   const astroPkg = {
     name: "velu-docs-site",
     version: "0.0.1",
@@ -487,9 +717,10 @@ const filteredSidebar = sidebar.filter((entry: any) => {
       preview: "astro preview",
     },
     dependencies: {
-      astro: "^5.1.0",
-      "@astrojs/starlight": "^0.32.0",
+      astro: "^5.12.0",
+      "@astrojs/starlight": "^0.35.0",
       sharp: "^0.33.0",
+      "starlight-ion-theme": "^2.3.0",
     },
   };
   writeFileSync(join(outDir, "package.json"), JSON.stringify(astroPkg, null, 2) + "\n", "utf-8");
@@ -513,7 +744,7 @@ const filteredSidebar = sidebar.filter((entry: any) => {
     "utf-8"
   );
 
-  // ── 9. Generate _server.mjs — programmatic dev/build/preview ────────────────
+  // ── 10. Generate _server.mjs — programmatic dev/build/preview ───────────────
   const serverScript = `import { dev, build, preview } from 'astro';
 import { watch } from 'node:fs';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from 'node:fs';
@@ -623,7 +854,7 @@ if (command === 'dev') {
 `;
   writeFileSync(join(outDir, "_server.mjs"), serverScript, "utf-8");
 
-  // ── 10. Generate .gitignore ──────────────────────────────────────────────
+  // ── 11. Generate .gitignore ──────────────────────────────────────────────
   writeFileSync(
     join(outDir, ".gitignore"),
     `.astro/\nnode_modules/\ndist/\n`,

package/src/cli.ts

@@ -38,6 +38,7 @@ function init(targetDir: string) {
   // velu.json
   const config = {
     $schema: "https://raw.githubusercontent.com/aravindc26/velu/main/schema/velu.schema.json",
+    theme: "violet" as const,
     navigation: {
       tabs: [
         {

package/src/themes.ts

@@ -0,0 +1,358 @@
+// ── Types ────────────────────────────────────────────────────────────────────
+
+interface ColorSet {
+  accentLow: string;
+  accent: string;
+  accentHigh: string;
+  white: string;
+  gray1: string;
+  gray2: string;
+  gray3: string;
+  gray4: string;
+  gray5: string;
+  gray6: string;
+  gray7: string;
+  black: string;
+}
+
+interface ThemePreset {
+  dark: ColorSet;
+  light: ColorSet;
+  font?: string;
+  fontMono?: string;
+}
+
+interface VeluColors {
+  primary?: string;
+  light?: string;
+  dark?: string;
+}
+
+interface VeluStyling {
+  codeblocks?: {
+    theme?: string | { light: string; dark: string };
+  };
+}
+
+interface ThemeConfig {
+  theme?: string;
+  colors?: VeluColors;
+  appearance?: "system" | "light" | "dark";
+  styling?: VeluStyling;
+}
+
+// ── Color utilities ──────────────────────────────────────────────────────────
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ];
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  const clamp = (v: number) => Math.round(Math.max(0, Math.min(255, v)));
+  return (
+    "#" +
+    [clamp(r), clamp(g), clamp(b)]
+      .map((c) => c.toString(16).padStart(2, "0"))
+      .join("")
+  );
+}
+
+function mixColors(hex1: string, hex2: string, weight: number): string {
+  const [r1, g1, b1] = hexToRgb(hex1);
+  const [r2, g2, b2] = hexToRgb(hex2);
+  return rgbToHex(
+    r1 * weight + r2 * (1 - weight),
+    g1 * weight + g2 * (1 - weight),
+    b1 * weight + b2 * (1 - weight)
+  );
+}
+
+function deriveAccentPalette(primary: string): { dark: Pick<ColorSet, "accentLow" | "accent" | "accentHigh">; light: Pick<ColorSet, "accentLow" | "accent" | "accentHigh"> } {
+  return {
+    dark: {
+      accentLow: mixColors(primary, "#000000", 0.3),
+      accent: mixColors(primary, "#ffffff", 0.2),
+      accentHigh: mixColors(primary, "#ffffff", 0.8),
+    },
+    light: {
+      accentLow: mixColors(primary, "#ffffff", 0.15),
+      accent: primary,
+      accentHigh: mixColors(primary, "#000000", 0.55),
+    },
+  };
+}
+
+// ── Gray palettes ────────────────────────────────────────────────────────────
+// Starlight convention: gray-1 = strongest foreground, gray-7 = subtlest
+// In dark mode: gray-1 is light, gray-7 is dark
+// In light mode: gray-1 is dark, gray-7 is light
+// --sl-color-white = foreground extreme, --sl-color-black = background extreme
+
+const GRAY_SLATE = {
+  dark: {
+    white: "#ffffff",
+    gray1: "#eceef2",
+    gray2: "#c0c2c7",
+    gray3: "#888b96",
+    gray4: "#545861",
+    gray5: "#353841",
+    gray6: "#24272f",
+    gray7: "#17181c",
+    black: "#13141a",
+  },
+  light: {
+    white: "#13141a",
+    gray1: "#17181c",
+    gray2: "#24272f",
+    gray3: "#545861",
+    gray4: "#888b96",
+    gray5: "#c0c2c7",
+    gray6: "#eceef2",
+    gray7: "#f5f6f8",
+    black: "#ffffff",
+  },
+};
+
+const GRAY_ZINC = {
+  dark: {
+    white: "#ffffff",
+    gray1: "#ececef",
+    gray2: "#bfc0c4",
+    gray3: "#878890",
+    gray4: "#53545c",
+    gray5: "#34353b",
+    gray6: "#23242a",
+    gray7: "#17171a",
+    black: "#121214",
+  },
+  light: {
+    white: "#121214",
+    gray1: "#17171a",
+    gray2: "#23242a",
+    gray3: "#53545c",
+    gray4: "#878890",
+    gray5: "#bfc0c4",
+    gray6: "#ececef",
+    gray7: "#f5f5f7",
+    black: "#ffffff",
+  },
+};
+
+const GRAY_STONE = {
+  dark: {
+    white: "#ffffff",
+    gray1: "#eeeceb",
+    gray2: "#c3bfbb",
+    gray3: "#8c8680",
+    gray4: "#585550",
+    gray5: "#383532",
+    gray6: "#272421",
+    gray7: "#1a1816",
+    black: "#141210",
+  },
+  light: {
+    white: "#141210",
+    gray1: "#1a1816",
+    gray2: "#272421",
+    gray3: "#585550",
+    gray4: "#8c8680",
+    gray5: "#c3bfbb",
+    gray6: "#eeeceb",
+    gray7: "#f7f6f5",
+    black: "#ffffff",
+  },
+};
+
+// ── Theme presets ────────────────────────────────────────────────────────────
+
+const THEMES: Record<string, ThemePreset> = {
+  violet: {
+    dark: {
+      accentLow: "#1e1b4b",
+      accent: "#818cf8",
+      accentHigh: "#e0e7ff",
+      ...GRAY_SLATE.dark,
+    },
+    light: {
+      accentLow: "#e0e7ff",
+      accent: "#4f46e5",
+      accentHigh: "#1e1b4b",
+      ...GRAY_SLATE.light,
+    },
+  },
+
+  maple: {
+    dark: {
+      accentLow: "#2e1065",
+      accent: "#a78bfa",
+      accentHigh: "#ede9fe",
+      ...GRAY_ZINC.dark,
+    },
+    light: {
+      accentLow: "#ede9fe",
+      accent: "#7c3aed",
+      accentHigh: "#2e1065",
+      ...GRAY_ZINC.light,
+    },
+  },
+
+  palm: {
+    dark: {
+      accentLow: "#0c2d44",
+      accent: "#38bdf8",
+      accentHigh: "#e0f2fe",
+      ...GRAY_SLATE.dark,
+    },
+    light: {
+      accentLow: "#e0f2fe",
+      accent: "#0369a1",
+      accentHigh: "#0c2d44",
+      ...GRAY_SLATE.light,
+    },
+  },
+
+  willow: {
+    dark: {
+      accentLow: "#292524",
+      accent: "#a8a29e",
+      accentHigh: "#fafaf9",
+      ...GRAY_STONE.dark,
+    },
+    light: {
+      accentLow: "#f5f5f4",
+      accent: "#57534e",
+      accentHigh: "#1c1917",
+      ...GRAY_STONE.light,
+    },
+  },
+
+  linden: {
+    dark: {
+      accentLow: "#052e16",
+      accent: "#4ade80",
+      accentHigh: "#dcfce7",
+      ...GRAY_ZINC.dark,
+    },
+    light: {
+      accentLow: "#dcfce7",
+      accent: "#16a34a",
+      accentHigh: "#052e16",
+      ...GRAY_ZINC.light,
+    },
+    font: "'JetBrains Mono', 'Fira Code', 'Courier New', monospace",
+  },
+
+  almond: {
+    dark: {
+      accentLow: "#451a03",
+      accent: "#fbbf24",
+      accentHigh: "#fef3c7",
+      ...GRAY_STONE.dark,
+    },
+    light: {
+      accentLow: "#fef3c7",
+      accent: "#b45309",
+      accentHigh: "#451a03",
+      ...GRAY_STONE.light,
+    },
+  },
+
+  aspen: {
+    dark: {
+      accentLow: "#1e1b4b",
+      accent: "#818cf8",
+      accentHigh: "#e0e7ff",
+      ...GRAY_SLATE.dark,
+    },
+    light: {
+      accentLow: "#e0e7ff",
+      accent: "#4f46e5",
+      accentHigh: "#1e1b4b",
+      ...GRAY_SLATE.light,
+    },
+  },
+};
+
+// ── CSS generator ────────────────────────────────────────────────────────────
+
+function colorSetToCss(colors: ColorSet): string {
+  return [
+    `  --sl-color-accent-low: ${colors.accentLow};`,
+    `  --sl-color-accent: ${colors.accent};`,
+    `  --sl-color-accent-high: ${colors.accentHigh};`,
+    `  --sl-color-white: ${colors.white};`,
+    `  --sl-color-gray-1: ${colors.gray1};`,
+    `  --sl-color-gray-2: ${colors.gray2};`,
+    `  --sl-color-gray-3: ${colors.gray3};`,
+    `  --sl-color-gray-4: ${colors.gray4};`,
+    `  --sl-color-gray-5: ${colors.gray5};`,
+    `  --sl-color-gray-6: ${colors.gray6};`,
+    `  --sl-color-gray-7: ${colors.gray7};`,
+    `  --sl-color-black: ${colors.black};`,
+  ].join("\n");
+}
+
+function generateThemeCss(config: ThemeConfig): string {
+  const themeName = config.theme || "violet";
+  const preset = THEMES[themeName] || THEMES["violet"];
+
+  const darkColors: ColorSet = { ...preset.dark };
+  const lightColors: ColorSet = { ...preset.light };
+
+  // Apply color overrides
+  if (config.colors) {
+    const { primary, light, dark } = config.colors;
+
+    const lightAccent = light || primary;
+    const darkAccent = dark || primary;
+
+    if (lightAccent) {
+      const palette = deriveAccentPalette(lightAccent);
+      lightColors.accentLow = palette.light.accentLow;
+      lightColors.accent = palette.light.accent;
+      lightColors.accentHigh = palette.light.accentHigh;
+    }
+
+    if (darkAccent) {
+      const palette = deriveAccentPalette(darkAccent);
+      darkColors.accentLow = palette.dark.accentLow;
+      darkColors.accent = palette.dark.accent;
+      darkColors.accentHigh = palette.dark.accentHigh;
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push(`/* Velu Theme: ${themeName} */`);
+  lines.push("");
+
+  // Dark mode (Starlight default)
+  lines.push(":root {");
+  lines.push(colorSetToCss(darkColors));
+  if (preset.font) {
+    lines.push(`  --sl-font: ${preset.font};`);
+  }
+  if (preset.fontMono) {
+    lines.push(`  --sl-font-mono: ${preset.fontMono};`);
+  }
+  lines.push("}");
+  lines.push("");
+
+  // Light mode
+  lines.push(":root[data-theme='light'] {");
+  lines.push(colorSetToCss(lightColors));
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function getThemeNames(): string[] {
+  return Object.keys(THEMES);
+}
+
+export { generateThemeCss, getThemeNames, THEMES, ThemeConfig, VeluColors, VeluStyling };

package/src/validate.ts

@@ -21,6 +21,10 @@ interface VeluTab {
 
 interface VeluConfig {
   $schema?: string;
+  theme?: string;
+  colors?: { primary?: string; light?: string; dark?: string };
+  appearance?: "system" | "light" | "dark";
+  styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
     tabs?: VeluTab[];
     groups?: VeluGroup[];