@aravindc26/velu 0.11.1 → 0.11.4

package/package.json

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

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { resolve, join, dirname, delimiter } from "node:path";
-import { existsSync, mkdirSync, writeFileSync, readdirSync, copyFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, copyFileSync, cpSync, rmSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -195,13 +195,25 @@ async function paths(docsDir: string) {
 
 async function generateProject(docsDir: string): Promise<string> {
   const { build } = await import("./build.js");
-  // Place .velu-out inside CLI package dir so node_modules resolves
-  // naturally by walking up — avoids symlinks that Turbopack rejects.
-  const outDir = join(PACKAGE_ROOT, ".velu-out");
+  // Generate into the active docs project directory.
+  const outDir = join(docsDir, ".velu-out");
   build(docsDir, outDir);
   return outDir;
 }
 
+function samePath(a: string, b: string): boolean {
+  return resolve(a).replace(/\\/g, "/").toLowerCase() === resolve(b).replace(/\\/g, "/").toLowerCase();
+}
+
+function prepareRuntimeOutDir(docsOutDir: string): string {
+  const runtimeOutDir = join(PACKAGE_ROOT, ".velu-out");
+  if (samePath(docsOutDir, runtimeOutDir)) return runtimeOutDir;
+
+  rmSync(runtimeOutDir, { recursive: true, force: true });
+  cpSync(docsOutDir, runtimeOutDir, { recursive: true, force: true });
+  return runtimeOutDir;
+}
+
 async function buildStatic(outDir: string, docsDir: string) {
   await new Promise<void>((res, rej) => {
     const child = spawn("node", ["_server.mjs", "build"], {
@@ -245,10 +257,19 @@ function exportMarkdownRoutes(outDir: string) {
 }
 
 async function buildSite(docsDir: string) {
-  const outDir = await generateProject(docsDir);
-  await buildStatic(outDir, docsDir);
-  exportMarkdownRoutes(outDir);
-  const staticOutDir = join(outDir, "dist");
+  const docsOutDir = await generateProject(docsDir);
+  const runtimeOutDir = prepareRuntimeOutDir(docsOutDir);
+  await buildStatic(runtimeOutDir, docsDir);
+  exportMarkdownRoutes(runtimeOutDir);
+
+  if (!samePath(docsOutDir, runtimeOutDir)) {
+    const docsDistDir = join(docsOutDir, "dist");
+    const runtimeDistDir = join(runtimeOutDir, "dist");
+    rmSync(docsDistDir, { recursive: true, force: true });
+    cpSync(runtimeDistDir, docsDistDir, { recursive: true, force: true });
+  }
+
+  const staticOutDir = join(docsOutDir, "dist");
   console.log(`\n📁 Static site output: ${staticOutDir}`);
 }
 
@@ -269,8 +290,9 @@ function spawnServer(outDir: string, command: string, port: number, docsDir: str
 }
 
 async function run(docsDir: string, port: number) {
-  const outDir = await generateProject(docsDir);
-  spawnServer(outDir, "dev", port, docsDir);
+  const docsOutDir = await generateProject(docsDir);
+  const runtimeOutDir = prepareRuntimeOutDir(docsOutDir);
+  spawnServer(runtimeOutDir, "dev", port, docsDir);
 }
 
 // ── Parse args ───────────────────────────────────────────────────────────────────

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

@@ -151,14 +151,19 @@ function buildNavbarTabs(tree: unknown): Array<{
     ? (tree as { children: unknown[] }).children
     : [];
 
-  const rootFolder = rootChildren.find((child) => {
+  const rootFolders = rootChildren.filter((child) => {
     const node = child as PageTreeFolderNode;
     return node?.type === 'folder' && node.root === true;
-  }) as PageTreeFolderNode | undefined;
+  }) as PageTreeFolderNode[];
 
-  const tabFolders = Array.isArray(rootFolder?.children)
-    ? rootFolder!.children.filter((child) => (child as PageTreeFolderNode)?.type === 'folder') as PageTreeFolderNode[]
-    : rootChildren.filter((child) => (child as PageTreeFolderNode)?.type === 'folder') as PageTreeFolderNode[];
+  // Two shapes are supported:
+  // 1) Multiple root folders => each root folder is a top-level tab.
+  // 2) Single root folder containing tab folders as children.
+  const tabFolders: PageTreeFolderNode[] = rootFolders.length > 1
+    ? rootFolders
+    : (rootFolders.length === 1 && Array.isArray(rootFolders[0]?.children)
+      ? rootFolders[0].children.filter((child) => (child as PageTreeFolderNode)?.type === 'folder') as PageTreeFolderNode[]
+      : rootChildren.filter((child) => (child as PageTreeFolderNode)?.type === 'folder') as PageTreeFolderNode[]);
 
   const tabs = tabFolders
     .map((folder) => {
@@ -173,13 +178,7 @@ function buildNavbarTabs(tree: unknown): Array<{
         urls,
       };
     })
-    .filter((tab): tab is {
-      url: string;
-      title: ReactNode;
-      icon?: ReactNode;
-      description?: ReactNode;
-      urls: Set<string>;
-    } => tab !== null);
+    .filter((tab): tab is NonNullable<typeof tab> => tab !== null);
 
   return tabs.length > 0 ? tabs : undefined;
 }
@@ -257,6 +256,30 @@ function scopeTreeToTab<T extends { children?: unknown[] }>(
   if (!normalizedTab) return tree;
 
   const topChildren = Array.isArray(tree.children) ? tree.children : [];
+  const rootFolders = topChildren.filter((child) => {
+    const node = child as PageTreeFolderNode;
+    return node?.type === 'folder' && node.root === true;
+  }) as PageTreeFolderNode[];
+
+  // When docs have multiple top-level root folders (tabs), avoid rendering
+  // the sidebar root switcher. Show only the active tab's children.
+  if (rootFolders.length > 1) {
+    const activeTopTab = (containerSlug ?? tabSlug ?? '').trim().toLowerCase();
+    if (!activeTopTab) return tree;
+
+    const matchedRoot = rootFolders.find((folder) => {
+      const urls = collectFolderUrls(folder);
+      for (const url of urls) {
+        const segments = url.split('/').filter(Boolean).map((segment) => segment.toLowerCase());
+        if ((segments[0] ?? '') === activeTopTab) return true;
+      }
+      return false;
+    });
+
+    if (!matchedRoot || !Array.isArray(matchedRoot.children)) return tree;
+    return { ...tree, children: matchedRoot.children } as T;
+  }
+
   const rootFolder = topChildren.find((child) => {
     const node = child as PageTreeFolderNode;
     return node?.type === 'folder' && node.root === true;
@@ -265,7 +288,7 @@ function scopeTreeToTab<T extends { children?: unknown[] }>(
   if (!rootFolder || !Array.isArray(rootFolder.children)) return tree;
 
   const normalizedContainer = (containerSlug ?? '').trim().toLowerCase();
-  const matchingChildren = rootFolder.children.filter((child) => {
+  const matchingChildren = rootFolder.children.filter((child): child is PageTreeFolderNode => {
     const folder = child as PageTreeFolderNode;
     if (folder?.type !== 'folder') return false;
 
@@ -303,7 +326,6 @@ export default async function SlugLayout({ children, params }: SlugLayoutProps)
   const currentVersion = resolveCurrentVersion(resolvedParams.slug, versions);
   const currentProduct = resolveCurrentProduct(resolvedParams.slug, products);
   const { containerSlug, tabSlug: currentTabSlug } = resolveTabContext(resolvedParams.slug);
-
   const activePrefix = currentVersion?.slug ?? currentProduct?.slug;
   const containerScopedTree = filterTreeBySlugPrefix(source.getPageTree(locale), activePrefix);
   const rawTree = scopeTreeToTab(containerScopedTree, currentTabSlug, containerSlug);

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

@@ -556,9 +556,10 @@ export default async function Page({ params }: PageProps) {
 
   if (!page) notFound();
 
-  const MDX = page.data.body;
-  const sourceMarkdown = await loadMarkdownForSlug(pageSlug, locale, hasI18n);
   const pageDataRecord = (page.data as unknown) as Record<string, unknown>;
+  const MDX = pageDataRecord.body as any;
+  if (typeof MDX !== 'function') notFound();
+  const sourceMarkdown = await loadMarkdownForSlug(pageSlug, locale, hasI18n);
   const dataMarkdown = typeof pageDataRecord.processedMarkdown === 'string'
     ? String(pageDataRecord.processedMarkdown)
     : undefined;
@@ -589,8 +590,14 @@ export default async function Page({ params }: PageProps) {
   const playgroundDisplay = normalizePlaygroundDisplay(frontmatter.playground, apiConfig.playgroundDisplay);
   const proxyUrl = apiConfig.playgroundProxyEnabled ? '/api/proxy' : '';
   const authMethod = normalizeAuthMethod(frontmatter.authMethod, apiConfig.authMethod);
+  const inlineApiTitle = typeof pageDataRecord.title === 'string' && pageDataRecord.title.trim().length > 0
+    ? pageDataRecord.title
+    : (frontmatter.title ?? pageSlug);
+  const inlineApiDescription = typeof pageDataRecord.description === 'string'
+    ? pageDataRecord.description
+    : frontmatter.description;
   const inlineApiDoc = parsedApiFrontmatter
-    ? buildInlineApiDoc(parsedApiFrontmatter, page.data.title, page.data.description, authMethod, apiConfig.authName)
+    ? buildInlineApiDoc(parsedApiFrontmatter, inlineApiTitle, inlineApiDescription, authMethod, apiConfig.authName)
     : null;
   const hasPanelExamples = typeof effectiveMarkdown === 'string'
     && /<(?:Panel|RequestExample|ResponseExample)(?:\s|>)/.test(effectiveMarkdown);
@@ -616,7 +623,9 @@ export default async function Page({ params }: PageProps) {
       <div id="velu-api-toc-rail-host" />
     </div>
   ) : undefined;
-  const toc = hasChangelog ? parsedChangelog.toc : page.data.toc;
+  const pageToc = pageDataRecord.toc as any;
+  const pageFull = typeof pageDataRecord.full === 'boolean' ? pageDataRecord.full : undefined;
+  const toc = hasChangelog ? parsedChangelog.toc : pageToc;
   const tableOfContentHeader = apiTocHeader ?? (hasPanelExamples ? <div className="velu-toc-panel-rail" /> : undefined);
   const orderedPages = hasI18n ? source.getPages(locale) : source.getPages();
   const currentPageUrl = (typeof sourcePageUrl === 'string' && sourcePageUrl.trim())
@@ -643,12 +652,12 @@ export default async function Page({ params }: PageProps) {
   }
 
   return (
-    <DocsPage
-      toc={toc}
-      full={hasChangelog ? false : (hasApiTocRail ? false : page.data.full)}
-      tableOfContent={tableOfContentHeader ? { header: tableOfContentHeader } : undefined}
-      footer={{ enabled: false }}
-    >
+      <DocsPage
+        toc={toc}
+        full={hasChangelog ? false : (hasApiTocRail ? false : pageFull)}
+        tableOfContent={tableOfContentHeader ? { header: tableOfContentHeader } : undefined}
+        footer={{ enabled: false }}
+      >
       <div
         data-pagefind-body
         data-pagefind-meta={metaAttrs.join(',')}
@@ -836,17 +845,17 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
     height: Number(ogImageHeight),
   }));
   const twitterImages = twitterImagesRaw.map((entry) => toAbsoluteMetaUrl(siteOrigin, entry));
-  const openGraph: NonNullable<Metadata['openGraph']> = {
-    type: (mergedMetatags['og:type'] as NonNullable<Metadata['openGraph']>['type']) || 'website',
+  const openGraph: Metadata['openGraph'] = {
+    type: (mergedMetatags['og:type'] as any) || 'website',
     siteName: mergedMetatags['og:site_name'] || siteName,
     title: mergedMetatags['og:title'] || resolvedTitle,
     ...(resolvedDescription ? { description: mergedMetatags['og:description'] || resolvedDescription } : {}),
     url: mergedMetatags['og:url'] ? toAbsoluteMetaUrl(siteOrigin, mergedMetatags['og:url']) : canonical,
     ...(mergedMetatags['og:locale'] ? { locale: mergedMetatags['og:locale'] } : {}),
-    ...(openGraphImages.length > 0 ? { images: openGraphImages as NonNullable<Metadata['openGraph']>['images'] } : {}),
+    ...(openGraphImages.length > 0 ? { images: openGraphImages as any } : {}),
   };
-  const twitter: NonNullable<Metadata['twitter']> = {
-    card: (mergedMetatags['twitter:card'] as NonNullable<Metadata['twitter']>['card']) || 'summary_large_image',
+  const twitter: Metadata['twitter'] = {
+    card: (mergedMetatags['twitter:card'] as any) || 'summary_large_image',
     title: mergedMetatags['twitter:title'] || resolvedTitle,
     ...(resolvedDescription ? { description: mergedMetatags['twitter:description'] || resolvedDescription } : {}),
     ...(mergedMetatags['twitter:site'] ? { site: mergedMetatags['twitter:site'] } : {}),

package/src/engine/app/global.css

@@ -602,8 +602,8 @@ nextjs-portal {
 .velu-page-feedback-row {
   display: flex;
   align-items: center;
-  justify-content: space-between;
-  gap: 0.75rem;
+  justify-content: flex-start;
+  gap: 0.55rem;
   flex-wrap: wrap;
 }
 
@@ -619,6 +619,7 @@ nextjs-portal {
   display: inline-flex;
   align-items: center;
   gap: 0.5rem;
+  margin-left: 0.1rem;
 }
 
 .velu-page-feedback-btn {

package/src/engine/app/llms-file/route.ts

@@ -3,8 +3,8 @@ import {
   getSiteTitle,
   normalizePath,
   readCustomLlmsFile,
-  resolveRequestOrigin,
 } from '@/lib/llms';
+import { getSiteOrigin } from '@/lib/velu';
 
 export const dynamic = 'force-static';
 
@@ -24,7 +24,7 @@ function toSpecUrl(origin: string, spec: string): string {
   return `${origin}${normalizePath(trimmed)}`;
 }
 
-export async function GET(request: Request) {
+export async function GET() {
   const custom = await readCustomLlmsFile('llms.txt');
   if (custom !== null) {
     return new Response(custom, {
@@ -38,7 +38,7 @@ export async function GET(request: Request) {
   }
 
   const siteTitle = getSiteTitle();
-  const origin = resolveRequestOrigin(request);
+  const origin = getSiteOrigin();
   const pages = await collectLlmsPages();
   const docsPages = pages.filter((page) => !page.noindex && !(page.sourceKind === 'generated' && page.isOpenApiOperation));
   const openApiSpecs = Array.from(

package/src/engine/app/llms-full-file/route.ts

@@ -3,12 +3,12 @@ import {
   getSiteTitle,
   normalizePath,
   readCustomLlmsFile,
-  resolveRequestOrigin,
 } from '@/lib/llms';
+import { getSiteOrigin } from '@/lib/velu';
 
 export const dynamic = 'force-static';
 
-export async function GET(request: Request) {
+export async function GET() {
   const custom = await readCustomLlmsFile('llms-full.txt');
   if (custom !== null) {
     return new Response(custom, {
@@ -22,7 +22,7 @@ export async function GET(request: Request) {
   }
 
   const siteTitle = getSiteTitle();
-  const origin = resolveRequestOrigin(request);
+  const origin = getSiteOrigin();
   const pages = await collectLlmsPages({ includeMarkdown: true });
   const includedPages = pages.filter((page) => {
     if (page.noindex) return false;

package/src/engine/app/robots.txt/route.ts

@@ -3,6 +3,8 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getSeoConfig, getSiteOrigin } from '@/lib/velu';
 
+export const dynamic = 'force-static';
+
 async function readCustomRobotsFile(): Promise<string | null> {
   const docsDir = process.env.VELU_DOCS_DIR?.trim();
   if (docsDir) {

package/src/engine/app/rss-file/[...slug]/route.ts

@@ -6,7 +6,7 @@ import {
   parseChangelogFromMarkdown,
   parseFrontmatterValue,
 } from '@/lib/changelog';
-import { getLanguages } from '@/lib/velu';
+import { getLanguages, getSiteOrigin } from '@/lib/velu';
 
 interface RouteParams {
   slug?: string[];
@@ -85,7 +85,7 @@ export async function generateStaticParams() {
   return out;
 }
 
-export async function GET(request: Request, { params }: { params: Promise<RouteParams> }) {
+export async function GET(_request: Request, { params }: { params: Promise<RouteParams> }) {
   const resolvedParams = await params;
   const fullSlug = resolvedParams.slug ?? [];
 
@@ -120,14 +120,7 @@ export async function GET(request: Request, { params }: { params: Promise<RouteP
     });
   }
 
-  const requestUrl = new URL(request.url);
-  const forwardedHost = request.headers.get('x-forwarded-host') ?? request.headers.get('host');
-  const forwardedProto = request.headers.get('x-forwarded-proto') ?? requestUrl.protocol.replace(':', '');
-  const devPort = process.env.PORT?.trim();
-  const fallbackOrigin = (requestUrl.hostname === 'localhost' && requestUrl.port === '3000' && devPort)
-    ? `${requestUrl.protocol}//${requestUrl.hostname}:${devPort}`
-    : requestUrl.origin;
-  const origin = forwardedHost ? `${forwardedProto}://${forwardedHost}` : fallbackOrigin;
+  const origin = getSiteOrigin();
   const pagePath = normalizePath(fullSlug.join('/'));
   const pageUrl = `${origin}${pagePath}`;
   const rssUrl = `${pageUrl.replace(/\/$/, '')}/rss.xml`;

package/src/engine/app/sitemap.xml/route.ts

@@ -4,6 +4,8 @@ import { join } from 'node:path';
 import { collectLlmsPages, normalizePath } from '@/lib/llms';
 import { getSeoConfig, getSiteOrigin } from '@/lib/velu';
 
+export const dynamic = 'force-static';
+
 function escapeXml(value: string): string {
   return value
     .replace(/&/g, '&')

package/src/engine/components/openapi.tsx

@@ -766,26 +766,26 @@ function collectResponseHeaderFields(response: OpenApiRecord): NormalizedField[]
   const headers = toRecord(response.headers);
   if (!headers) return [];
 
-  return Object.entries(headers)
-    .map(([headerName, rawHeader]) => {
-      const headerObject = toRecord(rawHeader);
-      if (!headerObject) return null;
-
-      const schema = headerObjectSchema(headerObject);
-      const description = typeof headerObject.description === 'string'
-        ? headerObject.description
-        : (typeof schema?.description === 'string' ? schema.description : undefined);
-
-      return {
-        name: headerName,
-        type: resolveSchemaType(schema),
-        required: Boolean(headerObject.required),
-        deprecated: Boolean(headerObject.deprecated ?? schema?.deprecated),
-        defaultValue: stringifyDefaultValue(schema?.default),
-        description,
-      } satisfies NormalizedField;
-    })
-    .filter((field): field is NormalizedField => Boolean(field));
+  const fields: NormalizedField[] = [];
+  for (const [headerName, rawHeader] of Object.entries(headers)) {
+    const headerObject = toRecord(rawHeader);
+    if (!headerObject) continue;
+
+    const schema = headerObjectSchema(headerObject);
+    const description = typeof headerObject.description === 'string'
+      ? headerObject.description
+      : (typeof schema?.description === 'string' ? schema.description : undefined);
+
+    fields.push({
+      name: headerName,
+      type: resolveSchemaType(schema),
+      required: Boolean(headerObject.required),
+      deprecated: Boolean(headerObject.deprecated ?? schema?.deprecated),
+      defaultValue: stringifyDefaultValue(schema?.default),
+      description,
+    } satisfies NormalizedField);
+  }
+  return fields;
 }
 
 function renderAuthorizationSection(method: MethodInformation, ctx: RenderContext): ReactNode {
@@ -1591,6 +1591,11 @@ export async function VeluOpenAPI({
           && normalizeWebhookName(resolvedTarget.item.name) !== normalizeWebhookName(endpointPath))
       ),
   );
+  const fallbackTargetLabel = resolvedTarget
+    ? (resolvedTarget.type === 'operation'
+      ? `${resolvedTarget.item.method.toUpperCase()} ${resolvedTarget.item.path}`
+      : `WEBHOOK ${resolvedTarget.item.name}`)
+    : '';
 
   return (
     <section className={className}>
@@ -1598,9 +1603,7 @@ export async function VeluOpenAPI({
         <div className="velu-openapi-warning">
           <p>
             Could not find <code>{endpointMethod.toUpperCase()} {endpointPath}</code> in <code>{inlineDocument ? inlineDocumentId : schemaSource}</code>.
-            Showing <code>{resolvedTarget!.type === 'operation'
-              ? `${resolvedTarget.item.method.toUpperCase()} ${resolvedTarget.item.path}`
-              : `WEBHOOK ${resolvedTarget.item.name}`}</code> instead.
+            Showing <code>{fallbackTargetLabel}</code> instead.
           </p>
         </div>
       ) : null}

package/src/engine/lib/source.ts

@@ -99,9 +99,9 @@ function openApiSidebarMethodBadgePlugin() {
 
 export const source = loader({
   baseUrl: '/',
-  source: docsCollection.toFumadocsSource(),
+  source: docsCollection.toFumadocsSource() as any,
   plugins: [
-    openApiSidebarMethodBadgePlugin(),
+    openApiSidebarMethodBadgePlugin() as any,
     statusBadgesPlugin({
       renderBadge: (status: string) => {
         const normalized = status.trim().toLowerCase();