@aravindc26/velu 0.11.5 → 0.11.9

package/src/engine/lib/layout.shared.ts

@@ -1,68 +1,68 @@
-import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
-import { createElement } from 'react';
-import { VersionSwitcher } from '@/components/version-switcher';
-import { getExternalTabs, getNavbarAnchors, getSiteLogoAsset, getSiteName, getVersionOptions } from '@/lib/velu';
-
-export function baseOptions(): BaseLayoutProps {
-  const externalTabs = getExternalTabs();
-  const navAnchors = getNavbarAnchors();
-  const versions = getVersionOptions();
-  const siteName = getSiteName();
-  const logo = getSiteLogoAsset();
-  const lightLogo = logo.light ?? logo.dark;
-  const darkLogo = logo.dark ?? logo.light;
-  const logoHref = typeof logo.href === 'string' && logo.href.trim().length > 0 ? logo.href.trim() : '/';
-
-  const navTitle =
-    lightLogo || darkLogo
-      ? createElement(
-          'span',
-          { className: 'velu-nav-brand' },
-          lightLogo
-            ? createElement('img', {
-                src: lightLogo,
-                alt: siteName,
-                className: 'velu-nav-logo velu-nav-logo-light',
-              })
-            : null,
-          darkLogo
-            ? createElement('img', {
-                src: darkLogo,
-                alt: siteName,
-                className: 'velu-nav-logo velu-nav-logo-dark',
-              })
-            : null,
-        )
-      : siteName;
-
-  const links = [
-    ...externalTabs.map((tab: { label: string; href: string }) => ({
-      text: tab.label,
-      url: tab.href,
-      secondary: false,
-    })),
-    ...navAnchors
-      .filter((a): a is { anchor: string; href: string } => typeof a.href === 'string' && a.href.length > 0)
-      .map((a) => ({
-        text: a.anchor,
-        url: a.href,
-        secondary: true,
-      })),
-  ];
-
-  return {
-    nav: {
-      title: navTitle,
-      url: logoHref,
-      children:
-        versions.length > 1
-          ? createElement(
-              'div',
-              { className: 'velu-header-version-switcher' },
-              createElement(VersionSwitcher, { versions })
-            )
-          : undefined,
-    },
-    links,
-  };
-}
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+import { createElement } from 'react';
+import { VersionSwitcher } from '@/components/version-switcher';
+import { getExternalTabs, getNavbarAnchors, getSiteLogoAsset, getSiteName, getVersionOptions } from '@/lib/velu';
+
+export function baseOptions(): BaseLayoutProps {
+  const externalTabs = getExternalTabs();
+  const navAnchors = getNavbarAnchors();
+  const versions = getVersionOptions();
+  const siteName = getSiteName();
+  const logo = getSiteLogoAsset();
+  const lightLogo = logo.light ?? logo.dark;
+  const darkLogo = logo.dark ?? logo.light;
+  const logoHref = typeof logo.href === 'string' && logo.href.trim().length > 0 ? logo.href.trim() : '/';
+
+  const navTitle =
+    lightLogo || darkLogo
+      ? createElement(
+          'span',
+          { className: 'velu-nav-brand' },
+          lightLogo
+            ? createElement('img', {
+                src: lightLogo,
+                alt: siteName,
+                className: 'velu-nav-logo velu-nav-logo-light',
+              })
+            : null,
+          darkLogo
+            ? createElement('img', {
+                src: darkLogo,
+                alt: siteName,
+                className: 'velu-nav-logo velu-nav-logo-dark',
+              })
+            : null,
+        )
+      : siteName;
+
+  const links = [
+    ...externalTabs.map((tab: { label: string; href: string }) => ({
+      text: tab.label,
+      url: tab.href,
+      secondary: false,
+    })),
+    ...navAnchors
+      .filter((a): a is { anchor: string; href: string } => typeof a.href === 'string' && a.href.length > 0)
+      .map((a) => ({
+        text: a.anchor,
+        url: a.href,
+        secondary: true,
+      })),
+  ];
+
+  return {
+    nav: {
+      title: navTitle,
+      url: logoHref,
+      children:
+        versions.length > 1
+          ? createElement(
+              'div',
+              { className: 'velu-header-version-switcher' },
+              createElement(VersionSwitcher, { versions })
+            )
+          : undefined,
+    },
+    links,
+  };
+}

package/src/engine/lib/velu.ts

@@ -107,12 +107,37 @@ interface VeluSeoConfig {
   indexing?: 'navigable' | 'all' | string;
 }
 
+interface VeluMetadataConfig {
+  timestamp?: boolean;
+}
+
 interface VeluThemeAsset {
   light?: string;
   dark?: string;
   href?: string;
 }
 
+interface VeluFooterConfig {
+  socials?: Record<string, unknown> | VeluFooterSocialInput[];
+}
+
+interface VeluFooterSocialInput {
+  type?: string;
+  label?: string;
+  href?: string;
+  url?: string;
+  icon?: string;
+  iconType?: string;
+}
+
+export interface VeluFooterSocialLink {
+  key: string;
+  label: string;
+  href: string;
+  icon: string;
+  iconType?: string;
+}
+
 export interface VeluProductOption {
   product: string;
   slug: string;
@@ -123,6 +148,16 @@ export interface VeluProductOption {
   defaultPath: string;
 }
 
+export interface VeluDropdownOption {
+  dropdown: string;
+  slug: string;
+  description?: string;
+  icon?: string;
+  iconType?: string;
+  tabSlugs: string[];
+  defaultPath: string;
+}
+
 export interface VeluVersionOption {
   version: string;
   slug: string;
@@ -131,8 +166,16 @@ export interface VeluVersionOption {
   defaultPath: string;
 }
 
+interface VeluContextualCustomOption {
+  title: string;
+  description?: string;
+  icon?: string;
+  href: string;
+}
+
 interface VeluConfig {
   name?: string;
+  description?: string;
   title?: string;
   favicon?: string | VeluThemeAsset;
   logo?: string | VeluThemeAsset;
@@ -150,6 +193,13 @@ interface VeluConfig {
   asyncapi?: string | string[] | Record<string, unknown>;
   api?: VeluApiConfig;
   seo?: VeluSeoConfig;
+  metadata?: VeluMetadataConfig;
+  footer?: VeluFooterConfig;
+  footerSocials?: Record<string, unknown> | VeluFooterSocialInput[];
+  banner?: { content?: string; dismissible?: boolean };
+  contextual?: {
+    options?: Array<string | VeluContextualCustomOption>;
+  };
   navigation: {
     tabs?: VeluTab[];
     languages?: VeluLanguageNav[];
@@ -211,6 +261,12 @@ function pageBasename(page: string): string {
   return parts[parts.length - 1] ?? page;
 }
 
+function withTrailingSlashPath(path: string): string {
+  if (!path.startsWith('/')) return path;
+  if (path === '/' || path.endsWith('/')) return path;
+  return `${path}/`;
+}
+
 function findFirstPageInGroup(group: VeluGroup): string | undefined {
   for (const item of group.pages) {
     if (typeof item === 'string') return item;
@@ -237,6 +293,41 @@ function findFirstPageInTab(tab: VeluTab): string | undefined {
   return undefined;
 }
 
+function findFirstRouteInGroup(group: VeluGroup, tabSlug: string, parentGroupSlugs: string[] = []): string | undefined {
+  const nextGroupSlugs = group.slug ? [...parentGroupSlugs, group.slug] : parentGroupSlugs;
+
+  for (const item of group.pages) {
+    if (typeof item === 'string') {
+      return `/${[tabSlug, ...nextGroupSlugs, pageBasename(item)].filter(Boolean).join('/')}`;
+    }
+    if (isGroup(item)) {
+      const nested = findFirstRouteInGroup(item, tabSlug, nextGroupSlugs);
+      if (nested) return nested;
+    }
+  }
+  return undefined;
+}
+
+function resolveFirstRouteInTab(tab: VeluTab): string | undefined {
+  if (!tab.slug) return undefined;
+
+  if (tab.pages) {
+    for (const item of tab.pages) {
+      if (typeof item === 'string') return `/${tab.slug}/${pageBasename(item)}`;
+    }
+  }
+
+  if (tab.groups) {
+    for (const group of tab.groups) {
+      const nested = findFirstRouteInGroup(group, tab.slug);
+      if (nested) return nested;
+    }
+  }
+
+  if (typeof tab.href === 'string' && tab.href.trim().length > 0) return tab.href.trim();
+  return `/${tab.slug}`;
+}
+
 function parseVersionParts(version: string): number[] {
   const parts = version.match(/\d+/g);
   return parts ? parts.map((n) => Number(n)) : [];
@@ -252,6 +343,109 @@ function compareVersionParts(a: number[], b: number[]): number {
   return 0;
 }
 
+const FOOTER_SOCIAL_PRESETS: Record<string, { label: string; icon: string }> = {
+  x: { label: 'X', icon: 'x-twitter' },
+  twitter: { label: 'X', icon: 'x-twitter' },
+  github: { label: 'GitHub', icon: 'github' },
+  gitlab: { label: 'GitLab', icon: 'gitlab' },
+  linkedin: { label: 'LinkedIn', icon: 'linkedin' },
+  discord: { label: 'Discord', icon: 'discord' },
+  youtube: { label: 'YouTube', icon: 'youtube' },
+  facebook: { label: 'Facebook', icon: 'facebook' },
+  instagram: { label: 'Instagram', icon: 'instagram' },
+  slack: { label: 'Slack', icon: 'slack' },
+  medium: { label: 'Medium', icon: 'medium' },
+  reddit: { label: 'Reddit', icon: 'reddit' },
+};
+
+function normalizeSocialKey(value: string): string {
+  return value.trim().toLowerCase().replace(/[\s_]+/g, '-');
+}
+
+function titleCaseWords(value: string): string {
+  const normalized = value.trim().replace(/[_-]+/g, ' ');
+  if (!normalized) return 'Social';
+  return normalized
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function trimString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeFooterSocialMap(value: unknown): VeluFooterSocialLink[] {
+  if (!isRecord(value)) return [];
+  const links: VeluFooterSocialLink[] = [];
+  for (const [rawKey, rawHref] of Object.entries(value)) {
+    const href = trimString(rawHref);
+    if (!href) continue;
+    const key = normalizeSocialKey(rawKey);
+    if (!key) continue;
+    const preset = FOOTER_SOCIAL_PRESETS[key];
+    links.push({
+      key,
+      href,
+      label: preset?.label ?? titleCaseWords(key),
+      icon: preset?.icon ?? key,
+      iconType: 'brands',
+    });
+  }
+  return links;
+}
+
+function normalizeFooterSocialList(value: unknown): VeluFooterSocialLink[] {
+  if (!Array.isArray(value)) return [];
+  const links: VeluFooterSocialLink[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) continue;
+    const href = trimString(entry.href) ?? trimString(entry.url);
+    if (!href) continue;
+    const key = normalizeSocialKey(
+      trimString(entry.type) ?? trimString(entry.icon) ?? trimString(entry.label) ?? 'social',
+    );
+    const preset = FOOTER_SOCIAL_PRESETS[key];
+    links.push({
+      key,
+      href,
+      label: trimString(entry.label) ?? preset?.label ?? titleCaseWords(key),
+      icon: trimString(entry.icon) ?? preset?.icon ?? key,
+      iconType: trimString(entry.iconType) ?? 'brands',
+    });
+  }
+  return links;
+}
+
+function dedupeFooterSocialLinks(links: VeluFooterSocialLink[]): VeluFooterSocialLink[] {
+  const seen = new Set<string>();
+  const unique: VeluFooterSocialLink[] = [];
+  for (const link of links) {
+    const dedupeKey = `${link.href}::${link.icon}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    unique.push(link);
+  }
+  return unique;
+}
+
+export interface VeluBannerConfig {
+  content: string;
+  dismissible: boolean;
+}
+
+export function getBannerConfig(): VeluBannerConfig | null {
+  const config = loadVeluConfig();
+  const banner = config.banner;
+  if (!banner) return null;
+  const content = typeof banner.content === 'string' ? banner.content.trim() : '';
+  if (!content) return null;
+  return { content, dismissible: banner.dismissible === true };
+}
+
 export function getExternalTabs(): Array<{ label: string; href: string }> {
   const config = loadVeluConfig();
   const tabs = config.navigation?.tabs ?? [];
@@ -288,6 +482,14 @@ export function getGlobalAnchors(): VeluAnchor[] {
   );
 }
 
+export function getFooterSocials(): VeluFooterSocialLink[] {
+  const config = loadVeluConfig();
+  const source = config.footer?.socials ?? config.footerSocials;
+  const fromMap = normalizeFooterSocialMap(source);
+  const fromList = normalizeFooterSocialList(source);
+  return dedupeFooterSocialLinks([...fromMap, ...fromList]);
+}
+
 export interface VeluTabMenuDefinition {
   tab: string;
   items: Array<{
@@ -351,6 +553,46 @@ export function getLanguages(): string[] {
   return config.languages ?? [];
 }
 
+export function getDropdownOptions(): VeluDropdownOption[] {
+  const raw = loadRawConfig();
+  const navigation = isRecord(raw.navigation) ? raw.navigation : {};
+  const dropdowns = Array.isArray(navigation.dropdowns) ? navigation.dropdowns : [];
+  if (dropdowns.length === 0) return [];
+
+  const allTabs = loadVeluConfig().navigation.tabs ?? [];
+  const out: VeluDropdownOption[] = [];
+
+  dropdowns.forEach((entry, index) => {
+    if (!isRecord(entry)) return;
+    const dropdown = trimString(entry.dropdown);
+    if (!dropdown) return;
+
+    const slug = slugify(trimString(entry.slug) ?? dropdown, `dropdown-${index + 1}`);
+    const scopedTabs = allTabs.filter((tab) => {
+      const tabSlug = tab.slug ?? '';
+      return tabSlug === slug || tabSlug.startsWith(`${slug}/`);
+    });
+    const firstTab = scopedTabs[0];
+    const firstRoute = firstTab ? resolveFirstRouteInTab(firstTab) : undefined;
+    const href = trimString(entry.href);
+    const defaultPath = withTrailingSlashPath(firstRoute ?? href ?? `/${slug}`);
+
+    out.push({
+      dropdown,
+      slug,
+      description: trimString(entry.description),
+      icon: trimString(entry.icon),
+      iconType: trimString(entry.iconType),
+      tabSlugs: scopedTabs
+        .map((tab) => tab.slug)
+        .filter((tabSlug): tabSlug is string => typeof tabSlug === 'string' && tabSlug.length > 0),
+      defaultPath,
+    });
+  });
+
+  return out;
+}
+
 export function getProductOptions(): VeluProductOption[] {
   const config = loadVeluConfig();
   const products = (config.navigation.products ?? []).filter((p) => !p.hidden);
@@ -382,7 +624,7 @@ export function getProductOptions(): VeluProductOption[] {
       icon: product.icon,
       iconType: product.iconType,
       tabSlugs,
-      defaultPath,
+      defaultPath: withTrailingSlashPath(defaultPath),
     };
   });
 }
@@ -417,7 +659,7 @@ export function getVersionOptions(): VeluVersionOption[] {
       explicitDefault: version.default === true,
       versionParts: parseVersionParts(version.version),
       tabSlugs,
-      defaultPath,
+      defaultPath: withTrailingSlashPath(defaultPath),
       order: index,
     };
   });
@@ -478,6 +720,10 @@ export interface VeluResolvedSeoConfig {
   indexing: 'navigable' | 'all';
 }
 
+export interface VeluResolvedMetadataConfig {
+  timestamp: boolean;
+}
+
 function normalizePlaygroundDisplay(api: VeluApiConfig | undefined): PlaygroundDisplayMode {
   const display = api?.playground?.display;
   if (display === 'interactive' || display === 'simple' || display === 'none') return display;
@@ -623,6 +869,13 @@ export function getSeoConfig(): VeluResolvedSeoConfig {
   };
 }
 
+export function getMetadataConfig(): VeluResolvedMetadataConfig {
+  const config = loadVeluConfig();
+  return {
+    timestamp: config.metadata?.timestamp === true,
+  };
+}
+
 export function getSiteName(): string {
   const config = loadVeluConfig();
   const fromName = normalizeAssetPath(config.name);
@@ -632,6 +885,11 @@ export function getSiteName(): string {
   return 'Velu Docs';
 }
 
+export function getSiteDescription(): string | undefined {
+  const config = loadVeluConfig();
+  return normalizeAssetPath(config.description);
+}
+
 export function getSiteFavicon(): string | undefined {
   const config = loadVeluConfig();
   const asset = normalizeThemeAsset(config.favicon);
@@ -650,6 +908,51 @@ export function getSitePrimaryColor(): string | undefined {
   return normalizeAssetPath(colors.primary) ?? normalizeAssetPath(colors.light) ?? normalizeAssetPath(colors.dark);
 }
 
+export interface VeluContextualOption {
+  id: string;
+  title: string;
+  description: string;
+  href?: string;
+  type: 'builtin' | 'custom';
+}
+
+const CONTEXTUAL_PRESETS: Record<string, { title: string; description: string }> = {
+  copy: { title: 'Copy page', description: 'Copy page as Markdown for LLMs' },
+  view: { title: 'View as Markdown', description: 'View this page in Markdown format' },
+  chatgpt: { title: 'Open in ChatGPT', description: 'Ask questions about this page' },
+  claude: { title: 'Open in Claude', description: 'Ask questions about this page' },
+  perplexity: { title: 'Open in Perplexity', description: 'Ask questions about this page' },
+  grok: { title: 'Open in Grok', description: 'Ask questions about this page' },
+  mcp: { title: 'Copy MCP URL', description: 'Copy the MCP server URL' },
+  'add-mcp': { title: 'Copy MCP install command', description: 'Copy npx command to install MCP server' },
+  cursor: { title: 'Connect to Cursor', description: 'Install MCP Server on Cursor' },
+  vscode: { title: 'Connect to VS Code', description: 'Install MCP Server on VS Code' },
+};
+
+const DEFAULT_CONTEXTUAL_OPTIONS = ['copy', 'chatgpt', 'claude', 'add-mcp', 'cursor', 'vscode'];
+
+export function getContextualOptions(): VeluContextualOption[] {
+  const config = loadVeluConfig();
+  const raw = config.contextual?.options;
+
+  const ids = raw ?? DEFAULT_CONTEXTUAL_OPTIONS;
+
+  return ids.map((entry, index) => {
+    if (typeof entry === 'string') {
+      const preset = CONTEXTUAL_PRESETS[entry];
+      if (!preset) return null;
+      return { id: entry, title: preset.title, description: preset.description, type: 'builtin' as const };
+    }
+    return {
+      id: `custom-${index}`,
+      title: entry.title,
+      description: entry.description ?? '',
+      href: entry.href,
+      type: 'custom' as const,
+    };
+  }).filter((item): item is VeluContextualOption => item !== null);
+}
+
 export function getSiteOrigin(): string {
   const seo = getSeoConfig();
   const envCandidates = [

package/src/engine/next.config.mjs

@@ -9,6 +9,10 @@ const withMDX = createMDX({
 const config = {
   reactStrictMode: false,
   output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
+  // For static hosts without rewrite rules, emit directory routes
+  // (e.g. /docs/page/index.html) so extensionless URLs resolve.
+  trailingSlash: true,
+  skipTrailingSlashRedirect: true,
   distDir: 'dist',
   devIndicators: false,
   turbopack: {

package/src/validate.ts

@@ -115,6 +115,7 @@ type VeluOpenApiSource = string | string[] | Record<string, unknown>;
 
 interface VeluConfig {
   $schema?: string;
+  variables?: Record<string, string>;
   icons?: {
     library?: "fontawesome" | "lucide" | "tabler";
   };
@@ -145,6 +146,13 @@ interface VeluConfig {
       };
     };
   };
+  metadata?: {
+    timestamp?: boolean;
+  };
+  footer?: {
+    socials?: Record<string, unknown>;
+  };
+  footerSocials?: Record<string, unknown>;
   navigation: {
     openapi?: VeluOpenApiSource;
     asyncapi?: VeluOpenApiSource;