jamdesk 1.1.37 → 1.1.39

package/templates/docs.json

@@ -1,10 +1,58 @@
 {
   "name": "{{PROJECT_NAME}}",
+  "theme": "jam",
+  "colors": {
+    "primary": "#635BFF",
+    "light": "#7C75FF",
+    "dark": "#4F46E5"
+  },
+  "api": {
+    "openapi": [
+      "/openapi/example-api.yaml"
+    ],
+    "examples": {
+      "languages": [
+        "curl",
+        "python",
+        "javascript",
+        "go",
+        "ruby",
+        "csharp",
+        "java",
+        "rust",
+        "php"
+      ]
+    }
+  },
   "navigation": {
     "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",
+        "pages": [
+          { "page": "api-reference/openapi-example", "title": "OpenAPI Example" },
+          "api-reference/request-response-examples"
+        ]
       }
     ]
   }

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/openapi/example-api.yaml

@@ -0,0 +1,185 @@
+openapi: 3.0.3
+info:
+  title: Acme Support API
+  version: "1.0.0"
+  description: |
+    The Acme Support API lets you create and track customer support tickets.
+    Use it to post new issues from your product and keep users updated on status.
+servers:
+  - url: https://jamdesk-docs.jamdesk.app/api/playground/demo
+security: []
+paths:
+  /tickets:
+    get:
+      summary: List support tickets
+      description: Retrieve all open support tickets.
+      operationId: listTickets
+      responses:
+        "200":
+          description: Ticket list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tickets:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/TicketSummary"
+                  total:
+                    type: integer
+              example:
+                tickets:
+                  - id: "tkt_9S8L2"
+                    customer_id: "cus_2X9W8"
+                    subject: "Export stuck on step 3"
+                    priority: "high"
+                    status: "open"
+                    created_at: "2026-02-04T16:12:00Z"
+                total: 1
+    post:
+      summary: Create a support ticket
+      description: Create a new ticket for a customer issue or request.
+      operationId: createTicket
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTicketRequest"
+            example:
+              customer_id: "cus_2X9W8"
+              subject: "Export stuck on step 3"
+              priority: "high"
+              tags: ["export", "bug"]
+              message: "The export job fails with error 504 after 2 minutes."
+      responses:
+        "201":
+          description: Ticket created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Ticket"
+              example:
+                id: "tkt_9S8L2"
+                customer_id: "cus_2X9W8"
+                subject: "Export stuck on step 3"
+                priority: "high"
+                status: "open"
+                created_at: "2026-02-04T16:12:00Z"
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                code: "invalid_request"
+                message: "subject is required"
+  /tickets/{ticket_id}:
+    get:
+      summary: Get a support ticket
+      description: Retrieve a specific support ticket by its ID.
+      operationId: getTicket
+      parameters:
+        - name: ticket_id
+          in: path
+          required: true
+          description: Unique ticket identifier
+          schema:
+            type: string
+          example: "tkt_9S8L2"
+      responses:
+        "200":
+          description: Ticket details
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Ticket"
+              example:
+                id: "tkt_9S8L2"
+                customer_id: "cus_2X9W8"
+                subject: "Export stuck on step 3"
+                priority: "high"
+                status: "open"
+                tags: ["export", "bug"]
+                message: "The export job fails with error 504 after 2 minutes."
+                created_at: "2026-02-04T16:12:00Z"
+                updated_at: "2026-02-04T16:12:00Z"
+components:
+  schemas:
+    CreateTicketRequest:
+      type: object
+      required:
+        - customer_id
+        - subject
+        - message
+      properties:
+        customer_id:
+          type: string
+          description: Customer identifier in Acme.
+        subject:
+          type: string
+          description: Short summary of the issue.
+        priority:
+          type: string
+          enum: [low, normal, high, urgent]
+        tags:
+          type: array
+          items:
+            type: string
+        message:
+          type: string
+          description: Detailed problem description.
+    TicketSummary:
+      type: object
+      description: Abbreviated ticket for list responses (excludes message and tags).
+      properties:
+        id:
+          type: string
+        customer_id:
+          type: string
+        subject:
+          type: string
+        priority:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        created_at:
+          type: string
+          format: date-time
+    Ticket:
+      type: object
+      description: Full ticket detail including message and tags.
+      properties:
+        id:
+          type: string
+        customer_id:
+          type: string
+        subject:
+          type: string
+        priority:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        tags:
+          type: array
+          items:
+            type: string
+        message:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Error:
+      type: object
+      properties:
+        code:
+          type: string
+        message:
+          type: string

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>