jamdesk 1.1.38 → 1.1.40

package/templates/components/steps.mdx

@@ -0,0 +1,39 @@
+---
+title: Steps
+description: "Break multi-step processes into numbered instructions with Steps and Step components. Each step gets a title and supports rich content."
+---
+
+Use Steps for ordered instructions:
+
+<Steps>
+  <Step title="Install the CLI">
+    ```bash
+    npm install -g jamdesk
+    ```
+  </Step>
+  <Step title="Initialize your project">
+    ```bash
+    jamdesk init
+    ```
+  </Step>
+  <Step title="Start writing">
+    Open your project and create `.mdx` files. Each file becomes a page in your docs.
+  </Step>
+</Steps>
+
+## Usage
+
+```mdx
+<Steps>
+  <Step title="First step">
+    Description of what to do.
+  </Step>
+  <Step title="Second step">
+    Next instruction.
+  </Step>
+</Steps>
+```
+
+<Tip>
+Steps work well for setup guides, tutorials, and getting-started flows.
+</Tip>

package/templates/components/tabs-and-accordions.mdx

@@ -0,0 +1,65 @@
+---
+title: Tabs & Accordions
+description: "Organize content with Tabs for language or platform variants and AccordionGroup for collapsible FAQ-style sections that save vertical space."
+---
+
+## Tabs
+
+Show content in switchable panels:
+
+<Tabs>
+  <Tab title="React">
+    ```jsx
+    function App() {
+      return <h1>Hello React</h1>;
+    }
+    ```
+  </Tab>
+  <Tab title="Vue">
+    ```html
+    <template>
+      <h1>Hello Vue</h1>
+    </template>
+    ```
+  </Tab>
+  <Tab title="Svelte">
+    ```html
+    <h1>Hello Svelte</h1>
+    ```
+  </Tab>
+</Tabs>
+
+```mdx
+<Tabs>
+  <Tab title="React">
+    Content for the React tab.
+  </Tab>
+  <Tab title="Vue">
+    Content for the Vue tab.
+  </Tab>
+</Tabs>
+```
+
+## Accordions
+
+Collapsible sections for optional details:
+
+<AccordionGroup>
+  <Accordion title="What is Jamdesk?">
+    Jamdesk is a documentation platform that builds and hosts your docs from MDX files in a GitHub repository.
+  </Accordion>
+  <Accordion title="How do I deploy?">
+    Push to GitHub. Jamdesk builds and deploys automatically on every push.
+  </Accordion>
+  <Accordion title="Can I use a custom domain?">
+    Yes. Configure your custom domain in the Jamdesk dashboard under project settings.
+  </Accordion>
+</AccordionGroup>
+
+```mdx
+<AccordionGroup>
+  <Accordion title="Question here">
+    Answer here.
+  </Accordion>
+</AccordionGroup>
+```

package/templates/docs.json

@@ -1,6 +1,11 @@
 {
   "name": "{{PROJECT_NAME}}",
   "theme": "jam",
+  "colors": {
+    "primary": "#635BFF",
+    "light": "#7C75FF",
+    "dark": "#4F46E5"
+  },
   "api": {
     "openapi": [
       "/openapi/example-api.yaml"
@@ -23,8 +28,24 @@
     "groups": [
       {
         "group": "Getting Started",
+        "icon": "rocket",
         "pages": ["introduction", "quickstart"]
       },
+      {
+        "group": "Writing Content",
+        "icon": "pen",
+        "pages": ["writing/pages", "writing/components", "writing/code-blocks"]
+      },
+      {
+        "group": "Built-In Components",
+        "icon": "puzzle-piece",
+        "pages": [
+          "components/cards",
+          "components/callouts",
+          "components/tabs-and-accordions",
+          "components/steps"
+        ]
+      },
       {
         "group": "API Pages",
         "icon": "plug",

package/templates/introduction.mdx

@@ -1,19 +1,49 @@
 ---
 title: Introduction
-description: Welcome to your documentation
+description: "Starter project with example pages, components, and API reference. Edit MDX, customize your theme, and ship docs in minutes — preview locally or auto-deploy from GitHub."
 ---
 
-# Welcome to {{PROJECT_NAME}}
+Welcome to your Jamdesk starter project. Everything you need to ship a polished documentation site is in this repo — edit the MDX files, tweak `docs.json`, and you're live.
 
-This is your new documentation site powered by Jamdesk.
+<Tip>
+**Built-in AI search.** Click the sparkles button in the top-right corner of the header — chat is grounded on this site's pages and works out of the box.
+</Tip>
 
-## Getting Started
+## What's included
 
-Edit this file to customize your documentation. Add new MDX files and update `docs.json` to add them to the navigation.
+<Columns cols={2}>
+  <Card title="Ready-made pages" icon="file-lines">
+    Example pages for getting started, writing content, and API references.
+  </Card>
+  <Card title="50+ components" icon="puzzle-piece" href="/components/cards">
+    Cards, callouts, tabs, steps, code groups, accordions — no imports needed.
+  </Card>
+  <Card title="OpenAPI rendering" icon="plug" href="/api-reference/openapi-example">
+    Auto-generate endpoint pages from a YAML or JSON spec.
+  </Card>
+  <Card title="Auto-deploy" icon="rocket">
+    Push to GitHub and your docs build and deploy in seconds.
+  </Card>
+</Columns>
 
-## Features
+## A minimal Jamdesk project
 
-- **MDX Support** - Write documentation with React components
-- **Hot Reload** - See changes instantly during development
-- **Search** - Full-text search built in
-- **Themes** - Choose from multiple themes
+```text
+my-docs/
+├── docs.json          # Site config: theme, colors, navigation
+├── introduction.mdx   # This page
+└── quickstart.mdx     # Your getting-started guide
+```
+
+That's all you need. Add more `.mdx` files to add more pages — the file path becomes the URL.
+
+## Next steps
+
+<Columns cols={2}>
+  <Card title="Quickstart" icon="play" href="/quickstart">
+    Edit pages locally, customize, and deploy.
+  </Card>
+  <Card title="Components" icon="puzzle-piece" href="/components/cards">
+    Browse every built-in component with live examples.
+  </Card>
+</Columns>

package/templates/quickstart.mdx

@@ -1,20 +1,109 @@
 ---
 title: Quickstart
-description: Get up and running in minutes
+description: "Edit MDX files, preview locally with the Jamdesk CLI, then connect a GitHub repo for automatic deploys. Customize colors, branding, and navigation in docs.json."
 ---
 
-# Quickstart
+Your docs are built from MDX files in this repository. Edit them locally with the CLI, then connect to Jamdesk for automatic builds on every push.
 
-Follow these steps to get started with your documentation.
+## 1. Preview locally
 
-## Step 1: Edit docs.json
+Install the Jamdesk CLI:
 
-Configure your documentation settings in `docs.json`.
+<CodeGroup>
+```bash npm
+npm install -g jamdesk
+```
 
-## Step 2: Add Pages
+```bash brew
+brew install jamdesk/tap/jamdesk
+```
+</CodeGroup>
 
-Create new `.mdx` files and add them to the navigation in `docs.json`.
+Start the dev server with hot reload:
 
-## Step 3: Deploy
+```bash
+jamdesk dev
+```
 
-Push to your Git repository and your docs will be built automatically.
+Open [http://localhost:3000](http://localhost:3000). Edits to MDX files appear instantly.
+
+## 2. Edit a page
+
+Open any `.mdx` file and start writing. MDX supports standard Markdown plus Jamdesk components.
+
+```mdx
+---
+title: My Page
+description: A brief description for SEO
+---
+
+# Heading
+
+Regular markdown works — **bold**, *italic*, `code`, [links](https://example.com).
+
+<Tip>
+Jamdesk components like this Tip drop in without imports.
+</Tip>
+```
+
+## 3. Add a new page
+
+<Steps>
+  <Step title="Create an MDX file">
+    Add a new `.mdx` file anywhere in your project, for example `guides/deployment.mdx`.
+  </Step>
+  <Step title="Add it to navigation">
+    Open `docs.json` and add the page path to the `navigation` section:
+
+    ```json
+    {
+      "group": "Guides",
+      "pages": ["guides/deployment"]
+    }
+    ```
+  </Step>
+</Steps>
+
+## 4. Customize your site
+
+Everything is configured in `docs.json`:
+
+| Setting | What it does |
+|---------|-------------|
+| `name` | Site name shown in the header |
+| `colors` | Primary, light, and dark accent colors |
+| `logo` | Light and dark mode logo images |
+| `theme` | Visual theme (`jam`, `nebula`, or `pulsar`) |
+| `navigation` | Sidebar tabs, groups, and page order |
+| `navbar` | Top navigation links and buttons |
+
+<Tip>
+See the full configuration reference at [jamdesk.com/docs/config/docs-json-reference](https://jamdesk.com/docs/config/docs-json-reference).
+</Tip>
+
+## 5. Connect GitHub for auto-deploy
+
+Once your docs look right locally, hand off building and hosting to Jamdesk:
+
+<Steps>
+  <Step title="Push your code to GitHub">
+    Create a repository and push your project.
+  </Step>
+  <Step title="Connect on the dashboard">
+    Sign in at [dashboard.jamdesk.com](https://dashboard.jamdesk.com), create a project, and connect your repository.
+  </Step>
+  <Step title="Push changes">
+    Every push triggers an automatic build. Your site is live in seconds at `<slug>.jamdesk.app` or your custom domain.
+  </Step>
+</Steps>
+
+## What's next
+
+<Columns cols={2}>
+  <Card title="Components" icon="puzzle-piece" href="/components/cards">
+    Cards, callouts, tabs, steps, and more — all ready to use.
+  </Card>
+  <Card title="API Pages" icon="plug" href="/api-reference/openapi-example">
+    Render endpoint pages from an OpenAPI spec, or hand-author with components.
+  </Card>
+</Columns>

package/templates/writing/code-blocks.mdx

@@ -0,0 +1,80 @@
+---
+title: Code Blocks
+description: "Fenced code blocks with automatic syntax highlighting, optional file titles, and CodeGroup for multi-language examples side by side."
+---
+
+Fenced code blocks are automatically syntax-highlighted.
+
+## Basic code block
+
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+Add a language identifier after the opening fence for syntax highlighting:
+
+````mdx
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+````
+
+## With title
+
+Add a title after the language:
+
+```javascript server.js
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  res.send('Hello World');
+});
+
+app.listen(3000);
+```
+
+````mdx
+```javascript server.js
+const express = require('express');
+const app = express();
+app.listen(3000);
+```
+````
+
+## Code groups
+
+Show the same example in multiple languages:
+
+<CodeGroup>
+```javascript Node.js
+const response = await fetch('https://api.example.com/data');
+const data = await response.json();
+```
+
+```python Python
+import requests
+response = requests.get('https://api.example.com/data')
+data = response.json()
+```
+
+```bash cURL
+curl -X GET https://api.example.com/data
+```
+</CodeGroup>
+
+````mdx
+<CodeGroup>
+```javascript Node.js
+const response = await fetch('https://api.example.com/data');
+```
+
+```python Python
+response = requests.get('https://api.example.com/data')
+```
+</CodeGroup>
+````

package/templates/writing/components.mdx

@@ -0,0 +1,78 @@
+---
+title: Components
+description: "Choose the right component for the job — when to use Cards, Callouts, Tabs, Steps, and more. Live examples for every component live in the Components tab."
+---
+
+Jamdesk's MDX components are available in every page — no imports needed. This guide helps you pick the right one. For live examples of every component, see the **Components** tab in the sidebar.
+
+## Highlighting information
+
+<Note>
+**Note** — Helpful context that enhances understanding.
+</Note>
+
+<Info>
+**Info** — Neutral facts or supplementary details.
+</Info>
+
+<Tip>
+**Tip** — Best practices and "pro tips."
+</Tip>
+
+<Warning>
+**Warning** — Important caveats or requirements.
+</Warning>
+
+<Danger>
+**Danger** — Critical warnings (data loss, security).
+</Danger>
+
+<Check>
+**Check** — Success confirmations.
+</Check>
+
+Use the lightest one that conveys the urgency. Reach for `Warning` and `Danger` sparingly so they keep their weight.
+
+## Linking to other pages
+
+| Component | When to use |
+|-----------|-------------|
+| `<Card>` | A single feature or destination — title, icon, optional href. |
+| `<Columns>` | A grid of cards (2, 3, or 4 columns). Wraps multiple `<Card>` children. |
+
+```mdx
+<Columns cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/quickstart">
+    Get up and running in minutes.
+  </Card>
+  <Card title="Components" icon="puzzle-piece" href="/components/cards">
+    See every built-in component.
+  </Card>
+</Columns>
+```
+
+## Showing alternatives or steps
+
+| Component | When to use |
+|-----------|-------------|
+| `<Tabs>` + `<Tab>` | Equal alternatives the reader chooses between (languages, platforms, OSes). |
+| `<AccordionGroup>` + `<Accordion>` | Collapsed-by-default details (FAQs, advanced options). |
+| `<Steps>` + `<Step>` | A linear sequence the reader walks through in order. |
+| `<CodeGroup>` | Multi-language code blocks side by side with shared tab strip. |
+
+If readers do all the work, use `<Steps>`. If they pick one path, use `<Tabs>`. If most readers skip it, use `<AccordionGroup>`.
+
+## Documenting APIs
+
+| Component | When to use |
+|-----------|-------------|
+| `<ParamField>` | A request parameter (path, query, header, body). |
+| `<ResponseField>` | A response field. |
+| `<RequestExample>` | The request code samples panel. |
+| `<ResponseExample>` | The response payload(s) panel. |
+
+See the **API Pages** group for working examples.
+
+<Tip>
+For the full component reference (every prop, every variant) see [jamdesk.com/docs/components/overview](https://jamdesk.com/docs/components/overview).
+</Tip>

package/templates/writing/pages.mdx

@@ -0,0 +1,59 @@
+---
+title: Pages
+description: "How MDX files become pages, how frontmatter sets titles and descriptions, and how file paths map to URLs in your documentation site."
+---
+
+Every `.mdx` file in your project becomes a page. The file path determines the URL.
+
+## Frontmatter
+
+Each page starts with frontmatter — metadata between `---` fences:
+
+```mdx
+---
+title: My Page Title
+description: A short description for search engines
+---
+
+Your content starts here.
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Page title shown in the browser tab and sidebar |
+| `description` | No | Meta description for SEO |
+
+## File organization
+
+Your file structure maps directly to URLs:
+
+```
+introduction.mdx        → /introduction
+quickstart.mdx          → /quickstart
+guides/deployment.mdx   → /guides/deployment
+api/users/list.mdx      → /api/users/list
+```
+
+## Markdown features
+
+MDX supports all standard Markdown:
+
+- **Bold**, *italic*, `inline code`, and [links](https://jamdesk.com).
+- Ordered and unordered lists (you're reading one).
+- Fenced code blocks with syntax highlighting.
+- Tables, blockquotes, and headings (`##`, `###`, `####`).
+
+Lists, tables, and blockquotes render natively:
+
+| Format | Markdown | Renders as |
+|--------|----------|-----------|
+| Bold | `**bold**` | **bold** |
+| Italic | `*italic*` | *italic* |
+| Code | `` `code` `` | `code` |
+| Link | `[text](url)` | [text](https://jamdesk.com) |
+
+> Blockquotes pull a passage out of the flow. Use them sparingly.
+
+<Note>
+Headings on the page automatically appear in the right sidebar as a table of contents.
+</Note>

package/vendored/app/api/chat/[project]/route.ts

@@ -28,6 +28,7 @@ import { getDocsPath, getBaseUrl, trackChatAnalytics } from '@/lib/route-helpers
 import { getAnthropicClient } from '@/lib/anthropic-client';
 import { rewriteQueryForSearch } from '@/lib/query-rewriter';
 import { fetchDocsConfig } from '@/lib/r2-content';
+import { BCP47_LANGUAGE_RE } from '@/lib/language-utils';
 import { redis } from '@/lib/redis';
 import { CHAT_TOOLS } from '@/lib/chat-tools';
 import { rewriteSlugLinks } from '@/lib/link-rewriter';
@@ -44,7 +45,6 @@ const MAX_HISTORY = 10;
  *  Used both for searchQuery enrichment and to skip the rewriter. */
 const SHORT_FOLLOWUP_LEN = 60;
 const VALID_ROLES = new Set<string>(['user', 'assistant']);
-const VALID_LOCALE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
 
 export async function POST(
   request: NextRequest,
@@ -92,7 +92,7 @@ export async function POST(
 
   let clientLocale: string | undefined;
   if (body.locale !== undefined) {
-    if (typeof body.locale !== 'string' || !VALID_LOCALE_RE.test(body.locale)) {
+    if (typeof body.locale !== 'string' || !BCP47_LANGUAGE_RE.test(body.locale)) {
       return Response.json({ error: 'Invalid locale' }, { status: 400 });
     }
     clientLocale = body.locale;

package/vendored/app/api/docs-search/[project]/search/route.ts

@@ -22,6 +22,7 @@ import { getBaseUrl, trackServerAnalytics } from '@/lib/route-helpers';
 import { redis } from '@/lib/redis';
 import { fetchDocsConfig } from '@/lib/r2-content';
 import { isMultiLanguageConfig } from '@/lib/navigation-utils';
+import { BCP47_LANGUAGE_RE } from '@/lib/language-utils';
 import { log } from '@/lib/logger';
 
 export const runtime = 'nodejs';
@@ -37,10 +38,6 @@ const MAX_LIMIT = 20;
 const DEFAULT_LIMIT = 5;
 const MAX_QUERY_LENGTH = 500;
 const RATE_LIMIT_PER_MIN = 60;
-/** BCP-47-ish: 2-3 letter primary tag, optional 2-4 letter region/script.
- *  Matches the chat endpoint's VALID_LOCALE_RE — keep both contracts in sync.
- *  Limitation: 3-segment tags like `zh-Hant-HK` are rejected. Documented. */
-const VALID_LANGUAGE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
 const DEFAULT_LANGUAGE = 'en';
 
 export async function OPTIONS(_request: NextRequest) {
@@ -109,21 +106,17 @@ export async function POST(
 
   const { query, limit: rawLimit } = body;
 
-  // Validate language. `null` and `undefined` both default to 'en'
-  // (real-world clients send `language: null` from `?? null` fallbacks —
-  // rejecting them as 400 would be gratuitous). A non-string value or a
-  // string that doesn't match the BCP-47 pattern is a 400.
+  // `null` is treated as omitted: real-world clients emit `language: null`
+  // from `?? null` fallbacks, and rejecting them would be gratuitous.
   let language: string = DEFAULT_LANGUAGE;
-  let languageWasExplicit = false;
   if (body.language != null) {
-    if (typeof body.language !== 'string' || !VALID_LANGUAGE_RE.test(body.language)) {
+    if (typeof body.language !== 'string' || !BCP47_LANGUAGE_RE.test(body.language)) {
       return NextResponse.json(
         { error: 'Invalid language code' },
         { status: 400, headers: CORS_HEADERS },
       );
     }
     language = body.language;
-    languageWasExplicit = true;
   }
 
   if (!query || typeof query !== 'string' || query.trim().length === 0) {
@@ -154,47 +147,19 @@ export async function POST(
   // Apply the locale filter only when the project is configured for
   // multiple languages AND the per-project kill switch is not set.
   // Single-language projects' chunks have no locale metadata, so the
-  // strict filter would return zero. Run the config fetch and kill-switch
-  // read in parallel — fetchDocsConfig has a 5-min in-memory cache, and
-  // Redis is the bottleneck only on a cold cache. .catch() on the kill
-  // switch keeps a Redis blip from breaking searches.
-  const killSwitchPromise: Promise<boolean> = redis
-    ? redis.get(`searchLocaleFilter:${project}`)
-        .then((v) => v === 'disabled')
-        .catch(() => false)
-    : Promise.resolve(false);
-
-  let config: Awaited<ReturnType<typeof fetchDocsConfig>>;
-  let killSwitch: boolean;
-  try {
-    [config, killSwitch] = await Promise.all([
-      fetchDocsConfig(project),
-      killSwitchPromise,
-    ]);
-  } catch (err) {
-    // R2 outage — config unavailable. Asymmetric fail-mode:
-    //  - Caller sent an explicit language: 503 (don't silently leak
-    //    cross-language results to a caller who asked for filtering).
-    //  - Caller defaulted to 'en': fall back to today's no-filter behavior
-    //    so docs sites keep working through R2 incidents.
-    log('error', 'docs-search: fetchDocsConfig failed', {
-      project,
-      error: String(err),
-      languageWasExplicit,
-    });
-    if (languageWasExplicit) {
-      return NextResponse.json(
-        { error: 'Search temporarily unavailable' },
-        { status: 503, headers: CORS_HEADERS },
-      );
-    }
-    config = null;
-    killSwitch = await killSwitchPromise.catch(() => false);
-  }
+  // strict filter would return zero. Both reads tolerate failure (R2
+  // outage or Redis blip) by falling back to "filter disabled" — same
+  // pattern the chat endpoint uses.
+  const [config, killSwitch] = await Promise.all([
+    fetchDocsConfig(project).catch(() => null),
+    redis
+      ? redis.get(`searchLocaleFilter:${project}`)
+          .then((v) => v === 'disabled')
+          .catch(() => false)
+      : Promise.resolve(false),
+  ]);
 
   if (killSwitch) {
-    // Operators have flipped the kill switch for this project — log so we
-    // can spot escapes. Not an error, but worth surfacing.
     log('warn', 'docs-search: locale filter kill switch is enabled', {
       project,
     });