@aravindc26/velu 0.9.1 → 0.11.0

package/src/engine/_server.mjs

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module';
 import { watch } from 'node:fs';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
+import { normalizeConfigNavigation } from './lib/navigation-normalize.mjs';
 
 const require = createRequire(import.meta.url);
 const nextBinPath = require.resolve('next/dist/bin/next');
@@ -13,7 +14,7 @@ const contentDir = resolve('content', 'docs');
 
 function loadConfig() {
   const raw = readFileSync(join(docsDir, 'velu.json'), 'utf-8');
-  return JSON.parse(raw);
+  return normalizeConfigNavigation(JSON.parse(raw));
 }
 
 function pageBasename(page) {
@@ -25,6 +26,29 @@ function pageLabelFromSlug(slug) {
   return last.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+function isSeparator(item) {
+  return typeof item === 'object' && item !== null && 'separator' in item;
+}
+
+function isLink(item) {
+  return typeof item === 'object' && item !== null && 'href' in item && 'label' in item;
+}
+
+function isGroup(item) {
+  return typeof item === 'object' && item !== null && 'group' in item;
+}
+
+function metaEntry(item) {
+  if (typeof item === 'string') return item;
+  if (isSeparator(item)) return `---${item.separator}---`;
+  if (isLink(item)) {
+    return item.icon
+      ? `[${item.icon}][${item.label}](${item.href})`
+      : `[${item.label}](${item.href})`;
+  }
+  return String(item);
+}
+
 function buildArtifacts(config) {
   const pageMap = [];
   const metaFiles = [];
@@ -51,9 +75,17 @@ function buildArtifacts(config) {
         pageMap.push({ src: item, dest });
         pages.push(basename);
         trackFirstPage(dest);
-      } else {
+      } else if (isGroup(item)) {
         addGroup(item, groupDir);
-        pages.push(item.slug);
+        pages.push(item.hidden ? `!${item.slug}` : item.slug);
+      } else if (isSeparator(item)) {
+        pages.push(`---${item.separator}---`);
+      } else if (isLink(item)) {
+        pages.push(
+          item.icon
+            ? `[${item.icon}][${item.label}](${item.href})`
+            : `[${item.label}](${item.href})`
+        );
       }
     }
 
@@ -64,6 +96,7 @@ function buildArtifacts(config) {
     };
 
     if (group.icon) groupMeta.icon = group.icon;
+    if (group.description) groupMeta.description = group.description;
 
     metaFiles.push({ dir: groupDir, data: groupMeta });
   }
@@ -73,15 +106,19 @@ function buildArtifacts(config) {
 
     for (const group of tab.groups || []) {
       addGroup(group, tab.slug);
-      tabPages.push(group.slug);
+      tabPages.push(group.hidden ? `!${group.slug}` : group.slug);
     }
 
-    for (const page of tab.pages || []) {
-      const basename = pageBasename(page);
-      const dest = `${tab.slug}/${basename}`;
-      pageMap.push({ src: page, dest });
-      tabPages.push(basename);
-      trackFirstPage(dest);
+    for (const item of tab.pages || []) {
+      if (typeof item === 'string') {
+        const basename = pageBasename(item);
+        const dest = `${tab.slug}/${basename}`;
+        pageMap.push({ src: item, dest });
+        tabPages.push(basename);
+        trackFirstPage(dest);
+      } else {
+        tabPages.push(metaEntry(item));
+      }
     }
 
     const tabMeta = {
@@ -128,28 +165,100 @@ function writeMetaFiles(metaFiles) {
 function writeIndexPage(firstPage) {
   writeFileSync(
     join(contentDir, 'index.mdx'),
-    `---\ntitle: "Overview"\ndescription: Documentation powered by Velu + Fumadocs\n---\n\nimport { Card, Cards } from "fumadocs-ui/components/card"\nimport { Callout } from "fumadocs-ui/components/callout"\n\n<Callout type="info">\n  This site is powered by Velu + Fumadocs.\n</Callout>\n\n## Start here\n\n<Cards>\n  <Card\n    title="Read the docs"\n    href="/${firstPage}/"\n    description="Begin with the first page in your configured navigation."\n  />\n</Cards>\n`,
+    `---\ntitle: "Overview"\ndescription: Documentation powered by Velu\n---\n\nimport { Card, Cards } from "fumadocs-ui/components/card"\nimport { Callout } from "fumadocs-ui/components/callout"\n\n<Callout type="info">\n  Welcome to your documentation site.\n</Callout>\n\n## Start here\n\n<Cards>\n  <Card\n    title="Read the docs"\n    href="/${firstPage}/"\n    description="Begin with the first page in your configured navigation."\n  />\n</Cards>\n`,
+    'utf-8'
+  );
+}
+
+function writeLangContent(langCode, artifacts, isDefault, useLangFolders = false) {
+  const storagePrefix = useLangFolders ? langCode : (isDefault ? '' : langCode);
+  const urlPrefix = isDefault ? '' : langCode;
+
+  // Write meta files (prefixed for non-default)
+  const metaFiles = storagePrefix
+    ? artifacts.metaFiles.map((meta) => ({
+        dir: meta.dir ? `${storagePrefix}/${meta.dir}` : storagePrefix,
+        data: { ...meta.data },
+      }))
+    : artifacts.metaFiles;
+  writeMetaFiles(metaFiles);
+
+  // Copy pages using explicit source paths from velu.json
+  for (const { src, dest } of artifacts.pageMap) {
+    const srcPath = join(docsDir, `${src}.md`);
+    if (!existsSync(srcPath)) {
+      console.warn(`  \x1b[33m⚠\x1b[0m  Missing page source: ${src}.md (language: ${langCode})`);
+      continue;
+    }
+    const destPath = join(contentDir, storagePrefix ? `${storagePrefix}/${dest}.mdx` : `${dest}.mdx`);
+    processPage(srcPath, destPath, src);
+  }
+
+  // Index page
+  const href = urlPrefix ? `/${urlPrefix}/${artifacts.firstPage}/` : `/${artifacts.firstPage}/`;
+  const indexPath = storagePrefix ? join(contentDir, storagePrefix, 'index.mdx') : join(contentDir, 'index.mdx');
+  writeFileSync(
+    indexPath,
+    `---\ntitle: "Overview"\ndescription: Documentation powered by Velu\n---\n\nimport { Card, Cards } from "fumadocs-ui/components/card"\nimport { Callout } from "fumadocs-ui/components/callout"\n\n<Callout type="info">\n  Welcome to your documentation site.\n</Callout>\n\n## Start here\n\n<Cards>\n  <Card\n    title="Read the docs"\n    href="${href}"\n    description="Begin with the first page in your configured navigation."\n  />\n</Cards>\n`,
     'utf-8'
   );
 }
 
 function rebuildFromConfig() {
   const config = loadConfig();
-  const artifacts = buildArtifacts(config);
+  const navLanguages = config.navigation?.languages;
+  const simpleLanguages = config.languages || [];
 
   rmSync(contentDir, { recursive: true, force: true });
   mkdirSync(contentDir, { recursive: true });
 
-  writeMetaFiles(artifacts.metaFiles);
+  // ── Mode 1: Per-language navigation (Mintlify-style) ──────────────
+  if (navLanguages && navLanguages.length > 0) {
+    const rootPages = [];
 
-  for (const { src, dest } of artifacts.pageMap) {
-    const srcPath = join(docsDir, `${src}.md`);
-    if (!existsSync(srcPath)) continue;
-    const destPath = join(contentDir, `${dest}.mdx`);
-    processPage(srcPath, destPath, src);
+    for (let i = 0; i < navLanguages.length; i++) {
+      const langEntry = navLanguages[i];
+      const langCode = langEntry.language;
+      const isDefault = i === 0;
+
+      // Build artifacts using this language's own tabs
+      const langConfig = { ...config, navigation: { ...config.navigation, tabs: langEntry.tabs } };
+      const artifacts = buildArtifacts(langConfig);
+
+      writeLangContent(langCode, artifacts, isDefault, true);
+      rootPages.push(`!${langCode}`);
+    }
+
+    // Write root meta with default tabs + hidden language folders
+    writeFileSync(
+      join(contentDir, 'meta.json'),
+      JSON.stringify({ pages: rootPages }, null, 2) + '\n',
+      'utf-8'
+    );
+
+    // Return the default language's page map for file watching
+    const defaultConfig = { ...config, navigation: { ...config.navigation, tabs: navLanguages[0].tabs } };
+    return buildArtifacts(defaultConfig).pageMap;
+  }
+
+  // ── Mode 2: Simple multi-lang (same nav, content in docs/<lang>/) ─
+  const artifacts = buildArtifacts(config);
+
+  const useLangFolders = simpleLanguages.length > 1;
+  writeLangContent(simpleLanguages[0] || 'en', artifacts, true, useLangFolders);
+
+  if (simpleLanguages.length > 1) {
+    const rootMetaPath = join(contentDir, 'meta.json');
+    const rootPages = [`!${simpleLanguages[0] || 'en'}`];
+
+    for (const lang of simpleLanguages.slice(1)) {
+      writeLangContent(lang, artifacts, false, true);
+      rootPages.push(`!${lang}`);
+    }
+
+    writeFileSync(rootMetaPath, JSON.stringify({ pages: rootPages }, null, 2) + '\n', 'utf-8');
   }
 
-  writeIndexPage(artifacts.firstPage);
   return artifacts.pageMap;
 }
 
@@ -244,7 +353,7 @@ const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 4321;
 
 if (command === 'dev') {
   console.log('');
-  console.log('  \x1b[36mvelu\x1b[0m  fumadocs dev');
+  console.log('  \x1b[36mvelu\x1b[0m  dev server');
   console.log('');
   console.log('  watching for file changes...');
   startWatcher();

package/src/engine/app/(docs)/[[...slug]]/layout.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { baseOptions } from '@/lib/layout.shared';
+import { source } from '@/lib/source';
+import { getLanguages, getVersionOptions, getProductOptions, type VeluVersionOption, type VeluProductOption } from '@/lib/velu';
+import { SidebarLinks } from '@/components/sidebar-links';
+import { ProductSwitcher } from '@/components/product-switcher';
+
+interface LayoutParams {
+  slug?: string[];
+}
+
+interface SlugLayoutProps {
+  children: ReactNode;
+  params: Promise<LayoutParams>;
+}
+
+function resolveLocale(slugInput: string[] | undefined): string {
+  const languages = getLanguages();
+  const defaultLanguage = languages[0] ?? 'en';
+  const slug = slugInput ?? [];
+  const firstSeg = slug[0];
+
+  return languages.includes(firstSeg ?? '') ? firstSeg! : defaultLanguage;
+}
+
+function resolveCurrentVersion(slugInput: string[] | undefined, versions: VeluVersionOption[]): VeluVersionOption | undefined {
+  if (versions.length === 0) return undefined;
+  const firstSeg = (slugInput ?? [])[0] ?? '';
+  return versions.find((v) => v.slug === firstSeg) ?? versions.find((v) => v.isDefault) ?? versions[0];
+}
+
+function filterTreeBySlugPrefix<T extends { children?: unknown[] }>(tree: T, prefix?: string): T {
+  if (!prefix) return tree;
+
+  const children = Array.isArray(tree.children) ? tree.children : [];
+
+  const filtered = children.filter((node) => {
+    if (typeof node !== 'object' || node === null) return false;
+    const entry = node as { url?: unknown; path?: unknown; $ref?: { metaFile?: unknown; file?: unknown } };
+    const candidates = [entry.url, entry.path, entry.$ref?.metaFile, entry.$ref?.file]
+      .filter((value): value is string => typeof value === 'string');
+    return candidates.some((value) => value.includes(`${prefix}/`));
+  });
+
+  if (filtered.length === 0) return tree;
+  return { ...tree, children: filtered } as T;
+}
+
+function resolveCurrentProduct(slugInput: string[] | undefined, products: VeluProductOption[]): VeluProductOption | undefined {
+  if (products.length === 0) return undefined;
+  const firstSeg = (slugInput ?? [])[0] ?? '';
+  return products.find((p) => p.slug === firstSeg) ?? products[0];
+}
+
+export default async function SlugLayout({ children, params }: SlugLayoutProps) {
+  const resolvedParams = await params;
+  const locale = resolveLocale(resolvedParams.slug);
+  const versions = getVersionOptions();
+  const products = getProductOptions();
+  const currentVersion = resolveCurrentVersion(resolvedParams.slug, versions);
+  const currentProduct = resolveCurrentProduct(resolvedParams.slug, products);
+
+  const activePrefix = currentVersion?.slug ?? currentProduct?.slug;
+  const tree = filterTreeBySlugPrefix(source.getPageTree(locale), activePrefix);
+
+  return (
+    <DocsLayout
+      tree={tree}
+      sidebar={{
+        collapsible: false,
+        banner: products.length > 1 ? (
+          <div className="velu-sidebar-banner">
+            <ProductSwitcher products={products} />
+          </div>
+        ) : undefined,
+        footer: <SidebarLinks />,
+      }}
+      {...baseOptions()}
+      themeSwitch={{ enabled: false }}
+    >
+      {children}
+    </DocsLayout>
+  );
+}
+
+export { generateStaticParams } from './page';

package/src/engine/app/(docs)/[[...slug]]/page.tsx

@@ -9,6 +9,7 @@ import {
 } from 'fumadocs-ui/layouts/docs/page';
 import { getMDXComponents } from '@/mdx-components';
 import { source } from '@/lib/source';
+import { getLanguages, getVersionOptions, getProductOptions } from '@/lib/velu';
 import { CopyPageButton } from '@/components/copy-page';
 
 interface RouteParams {
@@ -19,17 +20,79 @@ interface PageProps {
   params: Promise<RouteParams>;
 }
 
+function resolveLocaleSlug(slugInput: string[] | undefined) {
+  const languages = getLanguages();
+  const defaultLanguage = languages[0] ?? 'en';
+  const slug = slugInput ?? [];
+  const firstSeg = slug[0];
+  const hasLocalePrefix = languages.includes(firstSeg ?? '');
+
+  return {
+    defaultLanguage,
+    locale: hasLocalePrefix ? firstSeg! : defaultLanguage,
+    pageSlug: hasLocalePrefix ? slug.slice(1) : slug,
+  };
+}
+
+function resolveContextFromSlug(slugInput: string[] | undefined) {
+  const languages = getLanguages();
+  const versions = getVersionOptions();
+  const products = getProductOptions();
+  const slug = slugInput ?? [];
+  
+  // Check for language prefix
+  const firstSeg = slug[0];
+  const hasLocalePrefix = languages.includes(firstSeg ?? '');
+  const locale = hasLocalePrefix ? firstSeg! : (languages[0] ?? 'en');
+  const remainingSlug = hasLocalePrefix ? slug.slice(1) : slug;
+  
+  // Check for version/product in remaining slug
+  const contextSeg = remainingSlug[0] ?? '';
+  const version = versions.find((v) => v.slug === contextSeg);
+  const product = products.find((p) => p.slug === contextSeg);
+  
+  return {
+    locale,
+    version: version?.slug,
+    product: product?.slug,
+  };
+}
+
 export default async function Page({ params }: PageProps) {
   const resolvedParams = await params;
-  const page = source.getPage(resolvedParams.slug);
+  const { locale, pageSlug } = resolveLocaleSlug(resolvedParams.slug);
+  const { locale: filterLocale, version, product } = resolveContextFromSlug(resolvedParams.slug);
+  const hasI18n = getLanguages().length > 1;
+
+  const page = hasI18n ? source.getPage(pageSlug, locale) : source.getPage(pageSlug);
 
   if (!page) notFound();
 
   const MDX = page.data.body;
 
+  // Build pagefind filter attributes
+  const metaAttrs: string[] = [`title:${page.data.title}`];
+  const filterAttrs: string[] = [];
+  if (hasI18n) {
+    metaAttrs.push(`language:${filterLocale}`);
+    filterAttrs.push(`language:${filterLocale}`);
+  }
+  if (version) {
+    metaAttrs.push(`version:${version}`);
+    filterAttrs.push(`version:${version}`);
+  }
+  if (product) {
+    metaAttrs.push(`product:${product}`);
+    filterAttrs.push(`product:${product}`);
+  }
+
   return (
     <DocsPage toc={page.data.toc} full={page.data.full}>
-      <div data-pagefind-body data-pagefind-meta={`title:${page.data.title}`}>
+      <div
+        data-pagefind-body
+        data-pagefind-meta={metaAttrs.join(',')}
+        data-pagefind-filter={filterAttrs.length > 0 ? filterAttrs.join(',') : undefined}
+      >
         <div className="velu-title-row">
           <DocsTitle>{page.data.title}</DocsTitle>
           <CopyPageButton />
@@ -43,19 +106,36 @@ export default async function Page({ params }: PageProps) {
           />
         </DocsBody>
       </div>
+      <footer className="velu-footer">
+        Powered by <a href="https://getvelu.com" target="_blank" rel="noopener noreferrer">Velu</a>
+      </footer>
     </DocsPage>
   );
 }
 
 export async function generateStaticParams() {
-  const params = source.generateParams();
-  // Include root path for the optional catch-all [[...slug]]
-  return [{ slug: [] }, ...params];
+  const generated = source.generateParams('slug') as Array<{ slug?: string[] }>;
+  const seen = new Set<string>();
+
+  const nonRoot = generated.filter((entry) => {
+    const slug = entry.slug ?? [];
+    if (slug.length === 0) return false;
+    const key = slug.join('/');
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // Include root variants for optional catch-all [[...slug]] in export mode.
+  return [{}, { slug: undefined }, { slug: [] }, ...nonRoot];
 }
 
 export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
   const resolvedParams = await params;
-  const page = source.getPage(resolvedParams.slug);
+  const { locale, pageSlug } = resolveLocaleSlug(resolvedParams.slug);
+  const hasI18n = getLanguages().length > 1;
+
+  const page = hasI18n ? source.getPage(pageSlug, locale) : source.getPage(pageSlug);
 
   if (!page) notFound();
 

package/src/engine/app/(docs)/layout.tsx

@@ -1,16 +1,4 @@
 import type { ReactNode } from 'react';
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
-import { baseOptions } from '@/lib/layout.shared';
-import { source } from '@/lib/source';
-
 export default function DocsRootLayout({ children }: { children: ReactNode }) {
-  return (
-    <DocsLayout
-      tree={source.getPageTree()}
-      sidebar={{ collapsible: false }}
-      {...baseOptions()}
-    >
-      {children}
-    </DocsLayout>
-  );
+  return children;
 }