@aravindc26/velu 0.10.0 → 0.11.1

package/src/engine/middleware.ts

@@ -0,0 +1,66 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import redirectRules from '@/generated/redirects';
+import {
+  compileRedirectRules,
+  isExternalDestination,
+  normalizeRedirectRules,
+  resolveRedirect,
+} from '@/lib/redirects';
+
+const compiledRedirects = compileRedirectRules(normalizeRedirectRules(redirectRules));
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (pathname.startsWith('/rss-file')) {
+    return NextResponse.next();
+  }
+  if (pathname.startsWith('/llms-file') || pathname.startsWith('/llms-full-file')) {
+    return NextResponse.next();
+  }
+
+  if (pathname.endsWith('/rss.xml')) {
+    const rewritten = request.nextUrl.clone();
+    rewritten.pathname = `/rss-file${pathname.slice(0, -('/rss.xml'.length))}`;
+    return NextResponse.rewrite(rewritten);
+  }
+
+  if (pathname === '/llms.txt') {
+    const rewritten = request.nextUrl.clone();
+    rewritten.pathname = '/llms-file';
+    return NextResponse.rewrite(rewritten);
+  }
+
+  if (pathname === '/llms-full.txt') {
+    const rewritten = request.nextUrl.clone();
+    rewritten.pathname = '/llms-full-file';
+    return NextResponse.rewrite(rewritten);
+  }
+
+  if (pathname.endsWith('.md')) {
+    const rewritten = request.nextUrl.clone();
+    rewritten.pathname = `/md-file${pathname}`;
+    return NextResponse.rewrite(rewritten);
+  }
+
+  const redirect = resolveRedirect(pathname, compiledRedirects);
+  if (redirect) {
+    if (isExternalDestination(redirect.destination)) {
+      return NextResponse.redirect(redirect.destination, redirect.statusCode);
+    }
+
+    const target = request.nextUrl.clone();
+    target.pathname = redirect.destination;
+    if (!target.search && request.nextUrl.search) {
+      target.search = request.nextUrl.search;
+    }
+    return NextResponse.redirect(target, redirect.statusCode);
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/((?!_next|favicon.ico|sitemap.xml|robots.txt|assets|images).*)'],
+};

package/src/engine/next.config.mjs

@@ -7,8 +7,8 @@ const withMDX = createMDX({
 
 /** @type {import('next').NextConfig} */
 const config = {
-  reactStrictMode: true,
-  output: 'export',
+  reactStrictMode: false,
+  output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
   distDir: 'dist',
   devIndicators: false,
   turbopack: {

package/src/engine/public/icons/cursor-dark.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Ebene_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 466.73 532.09">
+  <!-- Generator: Adobe Illustrator 29.6.1, SVG Export Plug-In . SVG Version: 2.1.1 Build 9)  -->
+  <defs>
+    <style>
+      .st0 {
+        fill: #edecec;
+      }
+    </style>
+  </defs>
+  <path class="st0" d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+</svg>

package/src/engine/public/icons/cursor-light.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Ebene_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 466.73 532.09">
+  <!-- Generator: Adobe Illustrator 29.6.1, SVG Export Plug-In . SVG Version: 2.1.1 Build 9)  -->
+  <defs>
+    <style>
+      .st0 {
+        fill: #26251e;
+      }
+    </style>
+  </defs>
+  <path class="st0" d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/>
+</svg>

package/src/engine/source.config.ts

@@ -1,5 +1,89 @@
 import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
 import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
+import { transformerMetaHighlight } from '@shikijs/transformers';
+
+function remarkCodeFilenameToTitle() {
+  const booleanMetaFlags = new Set([
+    'wrap',
+    'copy',
+    'nocopy',
+    'lineNumbers',
+    'linenumbers',
+    'showLineNumbers',
+  ]);
+
+  function quoteTitle(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  }
+
+  function ensureTitleMeta(meta: string): string {
+    const trimmed = meta.trim();
+    if (!trimmed) return trimmed;
+    if (/\btitle\s*=/.test(trimmed)) return trimmed;
+
+    const fileWithRest = trimmed.match(/^([^\s]+?\.[a-z0-9_-]+)(\s+.*)?$/i);
+    if (fileWithRest) {
+      const file = fileWithRest[1];
+      const rest = (fileWithRest[2] ?? '').trim();
+      return rest ? `title="${quoteTitle(file)}" ${rest}` : `title="${quoteTitle(file)}"`;
+    }
+
+    if (!trimmed.includes('=') && !trimmed.includes('{') && !trimmed.includes('}')) {
+      if (booleanMetaFlags.has(trimmed)) return trimmed;
+      return `title="${quoteTitle(trimmed)}"`;
+    }
+
+    return trimmed;
+  }
+
+  function visit(node: any) {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === 'code' && typeof node.meta === 'string') {
+      let meta = node.meta.trim();
+      // Mint-style fence syntax: ```lang filename.ext
+      // Convert it into title metadata so code tabs can use file names.
+      meta = ensureTitleMeta(meta);
+
+      // Mint-style line highlight syntax: highlight=1 or highlight="1,3-5"
+      // Convert to Shiki meta-highlight format: {1,3-5}
+      const hlMatch = meta.match(/(?:^|\s)highlight=(?:"([^"]+)"|'([^']+)'|([^\s]+))/i);
+      if (hlMatch) {
+        const raw = (hlMatch[1] ?? hlMatch[2] ?? hlMatch[3] ?? '').trim();
+        const lineSpec = raw.replace(/[{}]/g, '');
+        meta = meta.replace(hlMatch[0], '').replace(/\s+/g, ' ').trim();
+        if (lineSpec && !/\{\s*\d[\d,\-\s]*\s*\}/.test(meta)) {
+          meta = `${meta} {${lineSpec}}`.trim();
+        }
+      }
+
+      // theme={null} is a Mint docs hint; remove it from fence meta.
+      meta = meta.replace(/\btheme=\{null\}\b/g, '').replace(/\s+/g, ' ').trim();
+      node.meta = meta;
+    }
+    if (node.type === 'code' && typeof node.meta !== 'string') {
+      return;
+    }
+
+    if (node.type === 'code' && node.meta === '') {
+      delete node.meta;
+    }
+
+    if (node.type === 'code' && typeof node.meta === 'string') {
+      node.meta = node.meta.trim();
+      if (!node.meta) {
+        delete node.meta;
+      }
+    }
+
+    const children = node.children;
+    if (Array.isArray(children)) {
+      for (const child of children) visit(child);
+    }
+  }
+
+  return (tree: any) => visit(tree);
+}
 
 export const docs = defineDocs({
   dir: 'content/docs',
@@ -14,4 +98,17 @@ export const docs = defineDocs({
   },
 });
 
-export default defineConfig();
+export default defineConfig({
+  mdxOptions: {
+    remarkPlugins: [remarkCodeFilenameToTitle],
+    rehypeCodeOptions: ({
+      lazy: false,
+      fallbackLanguage: 'bash',
+      transformers: [transformerMetaHighlight()],
+      langAlias: {
+        gradle: 'groovy',
+        proguard: 'properties',
+      },
+    } as any),
+  },
+});

package/src/engine/src/components/PageTitle.astro

@@ -405,19 +405,30 @@ const title = Astro.locals.starlightRoute.entry.data.title;
     }
   }, true);
 
-  // Hide ask bar only when user scrolls to the very bottom
-  window.addEventListener('scroll', function() {
+  // Hide ask bar only when truly near the page bottom.
+  function syncAskBarVisibility() {
     if (isPanelOpen()) return;
     var scrollTop = window.pageYOffset || document.documentElement.scrollTop;
     var docHeight = document.documentElement.scrollHeight;
     var winHeight = window.innerHeight;
-    if (docHeight <= winHeight + 10) return; // short pages: always show
-    if (docHeight - scrollTop - winHeight < 60) {
+    var bottomGap = docHeight - scrollTop - winHeight;
+    var nearBottomThreshold = 8;
+
+    if (docHeight <= winHeight + 2) {
+      askBar.classList.remove('velu-ask-bar-hidden');
+      return;
+    }
+
+    if (bottomGap <= nearBottomThreshold) {
       askBar.classList.add('velu-ask-bar-hidden');
     } else {
       askBar.classList.remove('velu-ask-bar-hidden');
     }
-  }, { passive: true });
+  }
+
+  window.addEventListener('scroll', syncAskBarVisibility, { passive: true });
+  window.addEventListener('resize', syncAskBarVisibility, { passive: true });
+  syncAskBarVisibility();
 
   document.onkeydown = function(e) {
     if (e.key === 'Escape' && isPanelOpen()) { closePanel(); }

package/src/engine/src/lib/velu.ts

@@ -1,15 +1,54 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { normalizeConfigNavigation } from '../../lib/navigation-normalize';
+const PRIMARY_CONFIG_NAME = 'docs.json';
+const LEGACY_CONFIG_NAME = 'velu.json';
+
+function resolveConfigPath(cwd: string): string {
+  const primary = resolve(cwd, PRIMARY_CONFIG_NAME);
+  if (existsSync(primary)) return primary;
+  return resolve(cwd, LEGACY_CONFIG_NAME);
+}
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+export interface VeluSeparator {
+  separator: string;
+}
+
+export interface VeluLink {
+  href: string;
+  label: string;
+  icon?: string;
+}
+
+export interface VeluAnchor {
+  anchor: string;
+  href?: string;
+  icon?: string;
+  color?: {
+    light: string;
+    dark: string;
+  };
+  tabs?: VeluTab[];
+  hidden?: boolean;
+}
+
+export interface VeluGlobalTab {
+  tab: string;
+  href: string;
+  icon?: string;
+}
+
 export interface VeluGroup {
   group: string;
   slug: string;
   icon?: string;
   tag?: string;
   expanded?: boolean;
-  pages: (string | VeluGroup)[];
+  description?: string;
+  hidden?: boolean;
+  pages: (string | VeluGroup | VeluSeparator | VeluLink)[];
 }
 
 export interface VeluTab {
@@ -17,7 +56,7 @@ export interface VeluTab {
   slug: string;
   icon?: string;
   href?: string;
-  pages?: string[];
+  pages?: (string | VeluSeparator | VeluLink)[];
   groups?: VeluGroup[];
 }
 
@@ -28,7 +67,12 @@ export interface VeluConfig {
   appearance?: 'system' | 'light' | 'dark';
   styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
-    tabs: VeluTab[];
+    tabs?: VeluTab[];
+    anchors?: VeluAnchor[];
+    global?: {
+      anchors?: VeluAnchor[];
+      tabs?: VeluGlobalTab[];
+    };
   };
 }
 
@@ -46,9 +90,9 @@ let _cachedConfig: VeluConfig | null = null;
 
 export function loadVeluConfig(): VeluConfig {
   if (_cachedConfig) return _cachedConfig;
-  const configPath = resolve(process.cwd(), 'velu.json');
+  const configPath = resolveConfigPath(process.cwd());
   const raw = readFileSync(configPath, 'utf-8');
-  _cachedConfig = JSON.parse(raw);
+  _cachedConfig = normalizeConfigNavigation(JSON.parse(raw));
   return _cachedConfig!;
 }
 
@@ -64,7 +108,7 @@ function veluGroupToSidebar(group: VeluGroup, tabSlug: string): any {
   for (const item of group.pages) {
     if (typeof item === 'string') {
       items.push(tabSlug + '/' + group.slug + '/' + pageBasename(item));
-    } else {
+    } else if (isGroup(item)) {
       items.push(veluGroupToSidebar(item, tabSlug));
     }
   }
@@ -74,10 +118,18 @@ function veluGroupToSidebar(group: VeluGroup, tabSlug: string): any {
   return result;
 }
 
+function isGroup(item: unknown): item is VeluGroup {
+  return typeof item === 'object' && item !== null && 'group' in item;
+}
+
 /** Get the first page dest path for a tab */
 function firstTabPage(tab: VeluTab): string | undefined {
-  if (tab.pages && tab.pages.length > 0) {
-    return tab.slug + '/' + pageBasename(tab.pages[0]);
+  if (tab.pages) {
+    for (const item of tab.pages) {
+      if (typeof item === 'string') {
+        return tab.slug + '/' + pageBasename(item);
+      }
+    }
   }
   if (tab.groups) {
     for (const g of tab.groups) {
@@ -91,25 +143,29 @@ function firstTabPage(tab: VeluTab): string | undefined {
 function firstGroupPage(group: VeluGroup, tabSlug: string): string | undefined {
   for (const item of group.pages) {
     if (typeof item === 'string') return tabSlug + '/' + group.slug + '/' + pageBasename(item);
-    const nested = firstGroupPage(item, tabSlug);
-    if (nested) return nested;
+    if (isGroup(item)) {
+      const nested = firstGroupPage(item, tabSlug);
+      if (nested) return nested;
+    }
   }
   return undefined;
 }
 
 // ── Public API ──────────────────────────────────────────────────────────────
 
-/** Build the full Starlight sidebar array from velu.json */
+/** Build the full Starlight sidebar array from docs.json/velu.json */
 export function getSidebar(): any[] {
   const config = loadVeluConfig();
   const sidebar: any[] = [];
 
-  for (const tab of config.navigation.tabs) {
+  for (const tab of config.navigation.tabs ?? []) {
     if (tab.href) continue;
     const items: any[] = [];
     if (tab.groups) for (const g of tab.groups) items.push(veluGroupToSidebar(g, tab.slug));
     if (tab.pages) {
-      for (const p of tab.pages) items.push(tab.slug + '/' + pageBasename(p));
+      for (const p of tab.pages) {
+        if (typeof p === 'string') items.push(tab.slug + '/' + pageBasename(p));
+      }
     }
     sidebar.push({ label: tab.tab, items });
   }
@@ -122,7 +178,7 @@ export function getTabs(): TabMeta[] {
   const config = loadVeluConfig();
   const tabs: TabMeta[] = [];
 
-  for (const tab of config.navigation.tabs) {
+  for (const tab of config.navigation.tabs ?? []) {
     if (tab.href) {
       tabs.push({ label: tab.tab, icon: tab.icon, href: tab.href, slugs: [] });
     } else {
@@ -144,10 +200,35 @@ export function getTabSidebarMap(): Record<string, string[]> {
   const config = loadVeluConfig();
   const map: Record<string, string[]> = {};
 
-  for (const tab of config.navigation.tabs) {
+  for (const tab of config.navigation.tabs ?? []) {
     if (tab.href) continue;
     map[tab.slug] = [tab.tab];
   }
 
   return map;
 }
+
+/** Get all anchors (navigation.anchors + navigation.global.anchors), excluding hidden ones */
+export function getAnchors(): VeluAnchor[] {
+  const config = loadVeluConfig();
+  const anchors: VeluAnchor[] = [];
+  if (config.navigation.anchors) {
+    anchors.push(...config.navigation.anchors.filter((a) => typeof a.href === 'string' && a.href.length > 0 && !a.hidden));
+  }
+  if (config.navigation.global?.anchors) {
+    anchors.push(...config.navigation.global.anchors.filter((a) => typeof a.href === 'string' && a.href.length > 0 && !a.hidden));
+  }
+  return anchors;
+}
+
+/** Get external tab links for the navbar */
+export function getExternalTabs(): { label: string; href: string; icon?: string }[] {
+  const config = loadVeluConfig();
+  const tabLinks = (config.navigation.tabs ?? [])
+    .filter((tab) => !!tab.href)
+    .map((tab) => ({ label: tab.tab, href: tab.href!, icon: tab.icon }));
+  const globalLinks = (config.navigation.global?.tabs ?? [])
+    .filter((tab) => !!tab.href)
+    .map((tab) => ({ label: tab.tab, href: tab.href, icon: tab.icon }));
+  return [...tabLinks, ...globalLinks];
+}