@veluai/velu 0.1.15 → 0.2.0

package/schema/velu.schema.json

@@ -40,6 +40,7 @@
       "type": "string",
       "description": "Path to the favicon, relative to the project root."
     },
+    "api": { "$ref": "#/$defs/api" },
     "logo": {
       "description": "Site logo shown in the header, replacing the name wordmark. A single path used in both themes, or per-theme light/dark images with an optional click-through href. Paths are relative to the project root.",
       "oneOf": [
@@ -169,6 +170,78 @@
     "navigation": {
       "$ref": "#/$defs/navContainer",
       "description": "Site navigation. Mintlify-compatible: products > versions > languages > tabs > groups > pages. Switchable axes (product/version/language) become URL path prefixes; the default value of each is unprefixed. Dropdowns are intentionally unsupported."
+    },
+    "url": {
+      "type": "string",
+      "description": "Production site origin (e.g. \"https://docs.example.com\"), no trailing slash. Used by the static build for canonical URLs, og:url, and sitemap.xml, and by llms.txt for absolute links."
+    },
+    "thumbnails": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Auto-generated OG (social share) image options. Build-only.",
+      "properties": {
+        "background": {
+          "type": "string",
+          "description": "Project-relative path to a background image for the OG cards (e.g. \"/images/og-background.png\"). Defaults to a brand-color glow."
+        }
+      }
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Search-engine optimization. Build-only: meta tags and sitemap behaviour applied when the site is built (not in the dev preview).",
+      "properties": {
+        "metatags": {
+          "type": "object",
+          "description": "Extra meta tags injected on every page, as a flat key→value map (e.g. \"google-site-verification\", \"og:image\").",
+          "additionalProperties": { "type": "string" }
+        },
+        "indexing": {
+          "type": "string",
+          "enum": ["navigable", "all"],
+          "description": "\"navigable\" (default) indexes only pages in navigation; \"all\" also includes hidden pages."
+        }
+      }
+    },
+    "contextual": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-page context menu — the \"Copy Page\" split-button + dropdown of agent/IDE actions shown at the top of each page. Mintlify-compatible. Unset → copy, view, chatgpt, claude.",
+      "required": ["options"],
+      "properties": {
+        "options": {
+          "type": "array",
+          "description": "Menu items, in order. Known string options, or custom { title, description, href } entries.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "copy", "assistant", "view", "download-pdf", "download-spec",
+                  "chatgpt", "claude", "perplexity", "grok", "aistudio", "devin", "windsurf",
+                  "mcp", "add-mcp", "cursor", "vscode", "devin-mcp"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["title", "href"],
+                "properties": {
+                  "title": { "type": "string", "description": "Menu item label." },
+                  "description": { "type": "string", "description": "Secondary line under the label." },
+                  "href": { "type": "string", "description": "URL to open." },
+                  "icon": { "type": "string", "description": "Lucide icon id." }
+                }
+              }
+            ]
+          }
+        },
+        "display": {
+          "type": "string",
+          "enum": ["header", "toc"],
+          "description": "Where the menu renders. Default \"header\"."
+        }
+      }
     }
   },
   "$defs": {
@@ -205,6 +278,8 @@
         "icon": { "type": "string", "description": "lucide icon id." },
         "expanded": { "type": "boolean", "description": "Start expanded." },
         "root": { "type": "string", "description": "Landing page path for the group." },
+        "openapi": { "$ref": "#/$defs/openapiRef" },
+        "api": { "$ref": "#/$defs/api" },
         "pages": { "$ref": "#/$defs/pages" }
       }
     },
@@ -216,11 +291,57 @@
         "tab": { "type": "string", "description": "Tab label (top nav)." },
         "icon": { "type": "string" },
         "href": { "type": "string", "description": "External/override link instead of in-site pages." },
+        "openapi": { "$ref": "#/$defs/openapiRef" },
+        "api": { "$ref": "#/$defs/api" },
         "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
         "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
         "pages": { "$ref": "#/$defs/pages" }
       }
     },
+    "api": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "API reference behaviour for OpenAPI-generated pages. Set at the root, or on a tab/group with `openapi` to override it for just that section.",
+      "properties": {
+        "server": {
+          "type": "string",
+          "description": "Base URL override for the playground + code samples (otherwise the spec's first server is used)."
+        },
+        "playground": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "display": {
+              "type": "string",
+              "enum": ["interactive", "simple", "none"],
+              "description": "Playground mode. \"none\" disables the proxy / live send."
+            },
+            "proxy": {
+              "type": "boolean",
+              "description": "Send Try-It requests through the dev proxy to avoid CORS (default true)."
+            }
+          }
+        },
+        "examples": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "languages": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["curl", "javascript", "python", "ruby"] },
+              "description": "Which request-snippet languages to generate."
+            }
+          }
+        }
+      }
+    },
+    "openapiRef": {
+      "description": "Path or URL to an OpenAPI spec (JSON/YAML), or an array of them. Auto-generates a page per operation, grouped by tag.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
     "anchor": {
       "type": "object",
       "additionalProperties": false,

package/src/navigation.js

@@ -186,9 +186,13 @@ function normalizeGroup(g) {
   };
 }
 
-/** A `pages[]` entry is either a string (page path) or a nested group. */
+/** A `pages[]` entry is a string (page path), a generated OpenAPI page
+ *  ({ apiPage, label, method }), or a nested group. */
 function normalizePageEntry(entry) {
   if (typeof entry === 'string') return { kind: 'page', pagePath: entry };
+  if (entry && entry.apiPage) {
+    return { kind: 'page', pagePath: entry.apiPage, label: entry.label, method: entry.method, api: true };
+  }
   return normalizeGroup(entry);
 }
 
@@ -430,5 +434,10 @@ function itemsFor(nodes, pagesMap, ctx) {
 function itemFor(pageNode, pagesMap, ctx) {
   const href = urlInCtx(pageNode.pagePath, ctx);
   const fm = pagesMap[href]?.frontmatter;
-  return { label: fm?.title ?? titleCase(lastSeg(href)), href };
+  // Generated API pages carry their own label + HTTP method (for the sidebar
+  // method badge); normal pages source their label from frontmatter.
+  const label = pageNode.label ?? fm?.title ?? titleCase(lastSeg(href));
+  const item = { label, href };
+  if (pageNode.method) item.method = pageNode.method;
+  return item;
 }

package/src/runtime/App.jsx

@@ -14,6 +14,7 @@ import {
   NavSelect,
   Toc,
   TocBar,
+  ContextMenu,
   Callout,
   Accordion,
   AccordionGroup,
@@ -47,6 +48,8 @@ import {
   ApiClient,
   ApiField,
   ApiSidebar,
+  ApiSamples,
+  NotFound,
   VeluMark,
 } from 'velu-ui';
 import { X, ChevronDown, ChevronUp } from 'lucide-react';
@@ -726,6 +729,9 @@ function DocsPage() {
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
+  // No renderable page for this route → show the 404 page (a clean centered
+  // takeover: header + footer stay, the docs sidebar/TOC are hidden).
+  const isNotFound = !PageComponent;
 
   // Switcher option sets (only render a switcher when an axis has >1
   // option). Anchors are pinned sidebar links shown in the context zone.
@@ -762,6 +768,27 @@ function DocsPage() {
     />
   );
 
+  // Keep document.title / meta description / <html lang> in sync on client-side
+  // navigation. The HTML is SSR'd with a per-page (build) or generic (dev) title;
+  // without this the tab title would stay frozen on the first page as you
+  // navigate the SPA, and JS-executing crawlers would read the stale value.
+  React.useEffect(() => {
+    const t = frontmatter.title;
+    document.title = isNotFound
+      ? `Page not found - ${site.name}`
+      : t && t !== site.name
+        ? `${t} - ${site.name}`
+        : site.name;
+    let descTag = document.querySelector('meta[name="description"]');
+    if (!descTag) {
+      descTag = document.createElement('meta');
+      descTag.setAttribute('name', 'description');
+      document.head.appendChild(descTag);
+    }
+    descTag.setAttribute('content', frontmatter.description || '');
+    document.documentElement.lang = nav?.activeLanguageCode || 'en';
+  }, [pathname, isNotFound, frontmatter.title, frontmatter.description, nav?.activeLanguageCode]);
+
   // Frontmatter title needs an id so scroll-spy + click-to-scroll work
   // against it like any other heading.
   const pageId = React.useMemo(() => {
@@ -1057,6 +1084,8 @@ function DocsPage() {
       data-chat-open={chatOpen ? 'true' : 'false'}
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
       data-drawer-open={drawerOpen ? 'true' : 'false'}
+      data-api={entry?.api ? 'true' : 'false'}
+      data-not-found={isNotFound ? 'true' : undefined}
     >
       {/* Scrim — visible at mobile while the drawer OR the chatbot
           sheet is open. Sits between the article (z-0) and the
@@ -1263,11 +1292,27 @@ function DocsPage() {
                 scrollPaddingBlockEnd: 'var(--s1)',
               }}
             >
-              <Sidebar
-                sections={nav?.sidebarSections ?? []}
-                activeHref={pathname}
-                linkComponent={RouterLink}
-              />
+              {entry?.api ? (
+                <ApiSidebar
+                  sections={(nav?.sidebarSections ?? []).map((s) => ({
+                    title: s.title,
+                    icon: s.icon,
+                    endpoints: (s.items ?? []).map((it) => ({
+                      method: it.method,
+                      label: it.label,
+                      href: it.href,
+                    })),
+                  }))}
+                  activeHref={pathname}
+                  linkComponent={RouterLink}
+                />
+              ) : (
+                <Sidebar
+                  sections={nav?.sidebarSections ?? []}
+                  activeHref={pathname}
+                  linkComponent={RouterLink}
+                />
+              )}
             </div>
             <button
               type="button"
@@ -1317,7 +1362,16 @@ function DocsPage() {
             scrollPaddingBlockEnd: `calc(${footerOverlap}px + 2rem)`,
           }}
         >
-          <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
+          {/* API reference pages put their code samples in the right rail
+              (where the TOC sits for normal pages). */}
+          {entry?.api && entry.operation ? (
+            <ApiSamples
+              samples={entry.samples}
+              responses={entry.operation.responses}
+            />
+          ) : (
+            <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
+          )}
         </aside>
       )}
 
@@ -1326,6 +1380,21 @@ function DocsPage() {
           and the right margin collapses to 0 while the chatbot is
           open via [data-chat-open="true"]). */}
       <div className="velu-docs-layout__center">
+        {isNotFound ? (
+          <main className="velu-404-main">
+            <NotFound
+              homeHref="/"
+              linkComponent={RouterLink}
+              onSearch={() =>
+                window.dispatchEvent(
+                  new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, metaKey: true }),
+                )
+              }
+              onAskAI={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+            />
+          </main>
+        ) : (
+        <>
         {/* Narrow-layout TOC bar — always in DOM, only visible at
             < 1024px (toggled by @container in toc-bar.css). Shares
             its `items` + `activeId` + `onSelect` API with the
@@ -1369,6 +1438,24 @@ function DocsPage() {
           </span>
         </button>
         <div className="velu-docs-layout__article">
+          {/* Per-page agent/IDE action bar: the section eyebrow + a
+              "Copy Page" split-button whose dropdown is driven by the
+              Mintlify-compatible `contextual` config. Renders nothing
+              when there's neither an eyebrow nor any enabled options. */}
+          <ContextMenu
+            eyebrow={
+              nav?.breadcrumb && nav.breadcrumb.length > 1
+                ? nav.breadcrumb[nav.breadcrumb.length - 2].label
+                : undefined
+            }
+            pageUrl={pathname}
+            title={frontmatter.title}
+            isApi={entry?.api === true}
+            siteName={site.name}
+            options={site.contextual?.options ?? []}
+            onAssistant={IS_DEV_PREVIEW ? undefined : () => askAI('')}
+          />
+
           {/* Page hero from MDX frontmatter. `.velu-hero` rules
               (in base.css) keep the title and description tightly
               grouped and create a clear break before the prose body. */}
@@ -1467,6 +1554,8 @@ function DocsPage() {
           )}
         </div>
       </main>
+        </>
+        )}
       </div>
 
       {/* Full site footer — only when the config provides link columns. Spans

package/templates/starter/api-reference/introduction.mdx

@@ -1,28 +1,43 @@
 ---
 title: Introduction
-description: How to read this API reference.
+description: How this API reference is generated.
 ---
 
-This section documents the example API. Endpoints are grouped in the
-sidebar; each page shows the request, parameters, and a sample
-response.
+The endpoints in this tab are generated automatically from an OpenAPI
+spec (`openapi.json`). Each operation becomes its own page — with
+parameters, request body, and responses — and an interactive **Try It**
+playground you can use to send real requests.
 
 <Callout type="note">
   This is a second tab ("API Reference"). Tabs let you keep guides and
-  reference docs in separate top-level sections of the same site.
+  reference docs in separate top-level sections of the same site. Point
+  the tab's `openapi` field at your own spec to replace this example.
 </Callout>
 
-## Base URL
+## How it works
 
-```
-https://api.example.com/v1
+Add an `openapi` field to a tab (or group) in `velu.json`:
+
+```json
+{
+  "tab": "API Reference",
+  "openapi": "/openapi.json"
+}
 ```
 
-## Authentication
+Velu reads the spec, groups the operations by their tag, and renders a
+page per endpoint. No hand-written endpoint pages required.
 
-Send your key as a bearer token:
+## The example API
 
-```bash
-curl https://api.example.com/v1/items \
-  -H "Authorization: Bearer YOUR_TOKEN"
-```
+This starter points at a live demo API — a small **product catalog**
+backed by [dummyjson.com](https://dummyjson.com). Open any endpoint in
+the sidebar, hit **Try It**, and send a real request:
+
+- **Get a product** — try `id` = `1`
+- **Search products** — try `q` = `phone`
+- **Add a product** — the body is pre-filled; Send returns a created product
+
+Requests are routed through the dev server's proxy so they aren't blocked
+by CORS. Set `api.playground.proxy` to `false` to send straight from the
+browser.

package/templates/starter/openapi.json

@@ -0,0 +1,160 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Product Catalog API",
+    "version": "1.0.0",
+    "description": "A friendly, fully-hosted example API — a product catalog backed by the live https://dummyjson.com service. Every operation hits the real API: list, search, fetch, create, update and delete products and see real responses."
+  },
+  "servers": [{ "url": "https://dummyjson.com" }],
+  "tags": [{ "name": "Products", "description": "Browse and manage the product catalog." }],
+  "paths": {
+    "/products": {
+      "get": {
+        "operationId": "listProducts",
+        "summary": "List products",
+        "description": "List products, with optional pagination.",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "How many products to return (0 returns all)." },
+          { "name": "skip", "in": "query", "schema": { "type": "integer" }, "description": "How many products to skip (for pagination)." }
+        ],
+        "responses": {
+          "200": {
+            "description": "A page of products.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }
+          }
+        }
+      }
+    },
+    "/products/search": {
+      "get": {
+        "operationId": "searchProducts",
+        "summary": "Search products",
+        "description": "Search the catalog by a free-text query.",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The search query (try `phone`)." }
+        ],
+        "responses": {
+          "200": {
+            "description": "Matching products.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }
+          }
+        }
+      }
+    },
+    "/products/{id}": {
+      "get": {
+        "operationId": "getProduct",
+        "summary": "Get a product",
+        "description": "Retrieve a single product by its id.",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The product id (try `1`)." }
+        ],
+        "responses": {
+          "200": {
+            "description": "The product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateProduct",
+        "summary": "Update a product",
+        "description": "Update fields on an existing product. (Simulated by the upstream API — the response reflects the change but nothing is persisted.)",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The product id." }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteProduct",
+        "summary": "Delete a product",
+        "description": "Delete a product by its id. (Simulated — the response includes `isDeleted` and `deletedOn`.)",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The product id." }
+        ],
+        "responses": {
+          "200": {
+            "description": "The deleted product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      }
+    },
+    "/products/add": {
+      "post": {
+        "operationId": "addProduct",
+        "summary": "Add a product",
+        "description": "Create a new product. (Simulated — the response echoes the body with a fresh `id`.)",
+        "tags": ["Products"],
+        "requestBody": {
+          "required": true,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } }
+        },
+        "responses": {
+          "201": {
+            "description": "The created product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Product": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer", "description": "Unique identifier." },
+          "title": { "type": "string", "description": "Product name." },
+          "description": { "type": "string", "description": "Product description." },
+          "category": { "type": "string", "description": "Category slug." },
+          "price": { "type": "number", "description": "Price in USD." },
+          "discountPercentage": { "type": "number", "description": "Discount, as a percentage." },
+          "rating": { "type": "number", "description": "Average customer rating (0–5)." },
+          "stock": { "type": "integer", "description": "Units in stock." },
+          "brand": { "type": "string", "description": "Brand name." },
+          "thumbnail": { "type": "string", "description": "Thumbnail image URL." }
+        }
+      },
+      "ProductList": {
+        "type": "object",
+        "properties": {
+          "products": { "type": "array", "description": "The products on this page.", "items": { "$ref": "#/components/schemas/Product" } },
+          "total": { "type": "integer", "description": "Total number of matching products." },
+          "skip": { "type": "integer", "description": "How many were skipped." },
+          "limit": { "type": "integer", "description": "How many were returned." }
+        }
+      },
+      "ProductInput": {
+        "type": "object",
+        "required": ["title"],
+        "properties": {
+          "title": { "type": "string", "description": "Product name." },
+          "description": { "type": "string", "description": "Product description." },
+          "category": { "type": "string", "description": "Category slug." },
+          "price": { "type": "number", "description": "Price in USD." }
+        },
+        "example": {
+          "title": "Velu Notebook",
+          "description": "A dotted-grid notebook for docs notes.",
+          "category": "stationery",
+          "price": 19.99
+        }
+      }
+    }
+  }
+}

package/templates/starter/velu.json

@@ -1,10 +1,14 @@
 {
   "$schema": "https://veludocs.com/velu.schema.json",
   "name": "Starter",
+  "url": "https://veludocs.com",
   "colors": {
     "primary": "#dc143c"
   },
   "favicon": "/favicon.svg",
+  "contextual": {
+    "options": ["copy", "view", "chatgpt", "claude", "mcp", "cursor", "vscode"]
+  },
   "navigation": {
     "anchors": [
       { "anchor": "Documentation", "icon": "book-open", "href": "https://veludocs.com" },
@@ -23,11 +27,15 @@
       {
         "tab": "API Reference",
         "icon": "terminal",
+        "openapi": "/openapi.json",
         "groups": [
-          { "group": "API Documentation", "pages": ["api-reference/introduction"] },
-          { "group": "Endpoint Examples", "pages": ["api-reference/endpoint/get", "api-reference/endpoint/create"] }
+          { "group": "API Documentation", "pages": ["api-reference/introduction"] }
         ]
       }
     ]
+  },
+  "api": {
+    "playground": { "proxy": true },
+    "examples": { "languages": ["curl", "javascript", "python", "ruby"] }
   }
 }

package/templates/starter/api-reference/endpoint/create.mdx

@@ -1,24 +0,0 @@
----
-title: Create item
-description: Create a new item.
----
-
-<MethodBadge method="POST" /> `/items`
-
-Creates an item and returns it.
-
-## Body
-
-<ApiField name="name" type="string" required>
-  Display name for the item.
-</ApiField>
-
-## Response
-
-```json
-{
-  "id": "itm_2",
-  "name": "New item",
-  "created_at": "2024-01-01T00:00:00Z"
-}
-```

package/templates/starter/api-reference/endpoint/get.mdx

@@ -1,27 +0,0 @@
----
-title: Get items
-description: Retrieve a list of items.
----
-
-<MethodBadge method="GET" /> `/items`
-
-Returns a paginated list of items.
-
-## Query parameters
-
-<ApiField name="limit" type="integer" default="20">
-  Maximum number of items to return.
-</ApiField>
-
-<ApiField name="cursor" type="string">
-  Pagination cursor from a previous response.
-</ApiField>
-
-## Response
-
-```json
-{
-  "data": [{ "id": "itm_1", "name": "Example" }],
-  "next_cursor": null
-}
-```