@clidey/dory 1.0.8 → 1.9.0

package/docs/configuration/navigation.mdx

@@ -0,0 +1,217 @@
+---
+title: 'Navigation'
+description: 'Configure the sidebar navigation using tabs, groups, and pages in dory.json.'
+---
+
+# Navigation
+
+The `navigation` object in `dory.json` defines the sidebar structure. Navigation is organized into three levels: **tabs**, **groups**, and **pages**.
+
+## Structure
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "Documentation",
+      "groups": [
+        {
+          "group": "Getting Started",
+          "pages": [
+            "introduction",
+            "installation",
+            "quick-start"
+          ]
+        },
+        {
+          "group": "Components",
+          "pages": [
+            "components/overview",
+            "components/code-blocks"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "API Reference",
+      "groups": [
+        {
+          "group": "Endpoints",
+          "pages": [
+            "api/users",
+            "api/workspaces"
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Tabs
+
+Tabs appear at the top of the sidebar. Use multiple tabs to separate major sections of your documentation.
+
+```json
+{
+  "tab": "Documentation",
+  "groups": [...]
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tab` | `string` | Tab label shown in the sidebar header. |
+| `groups` | `Group[]` | Navigation groups within this tab. |
+
+## Groups
+
+Groups are collapsible sections within a tab. They appear as labeled sections in the sidebar.
+
+```json
+{
+  "group": "Getting Started",
+  "pages": ["introduction", "installation"]
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `group` | `string` | Group label. |
+| `pages` | `string[]` | List of page paths within the group. |
+
+## Pages
+
+Pages are references to MDX files. Use paths **relative to the docs directory root**, without the `.mdx` extension.
+
+```json
+"pages": [
+  "introduction",
+  "getting-started/installation",
+  "components/code-blocks"
+]
+```
+
+A path like `"components/code-blocks"` maps to `docs/components/code-blocks.mdx`.
+
+<Note>
+  Page paths are case-sensitive and must exactly match the filename (without `.mdx`). Use lowercase with hyphens for consistency.
+</Note>
+
+## Single-Tab Setup
+
+For smaller documentation sites, one tab is enough:
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "Docs",
+      "groups": [
+        {
+          "group": "Overview",
+          "pages": ["introduction"]
+        },
+        {
+          "group": "Guides",
+          "pages": ["guides/setup", "guides/deployment"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Multi-Tab Setup
+
+Separate documentation types with multiple tabs:
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "Guides",
+      "groups": [
+        {
+          "group": "Getting Started",
+          "pages": ["introduction", "installation"]
+        }
+      ]
+    },
+    {
+      "tab": "API Reference",
+      "groups": [
+        {
+          "group": "Users",
+          "pages": ["api/create-user", "api/get-user", "api/delete-user"]
+        }
+      ]
+    },
+    {
+      "tab": "SDKs",
+      "groups": [
+        {
+          "group": "Client Libraries",
+          "pages": ["sdks/javascript", "sdks/python", "sdks/go"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Sidebar Extras
+
+Set `version` in `dory.json` to show the version card at the top of the sidebar. A page entry can be an object with a `badge`, which renders as a small label after the page name.
+
+```json dory.json
+{
+  "version": "1.0.8 · Latest",
+  "navigation": {
+    "tabs": [{
+      "tab": "Documentation",
+      "groups": [{
+        "group": "Writing Docs",
+        "pages": ["introduction", { "page": "components/overview", "badge": "New" }]
+      }]
+    }]
+  }
+}
+```
+
+API reference pages show their method in the sidebar automatically, taken from the page's `openapi` or `asyncapi` frontmatter.
+
+## Page Frontmatter
+
+Each MDX page should include frontmatter with `title` and `description`. These are used for the page title, meta tags, and breadcrumbs:
+
+```mdx
+---
+title: 'Installation'
+description: 'Install and configure Dory for your project.'
+---
+
+# Installation
+```
+
+<Tip>
+  Keep `title` concise (2–5 words). The `description` is used for SEO meta tags and appears in search results, so make it a full sentence.
+</Tip>
+
+### Lead Paragraph and Metadata Strip
+
+Add a `lead` string to show a larger introductory paragraph directly under the page title. Add a `meta` map to show a row of labelled facts below it. Keys are the labels and values are shown as written. YAML dates such as `2026-10-12` render as `12 Oct 2026`.
+
+```mdx
+---
+title: 'Introduction'
+description: 'What WhoDB is and how to get started.'
+lead: 'WhoDB is a database management tool for exploring schemas, managing data and visualizing relationships.'
+meta:
+  Edition: Community
+  Updated: 2026-10-12
+  Read: 4 min
+---
+```
+
+Pages without `lead` or `meta` show neither.

package/docs/configuration/theming.mdx

@@ -0,0 +1,166 @@
+---
+title: 'Theming'
+description: 'Customize your documentation site colors, fonts, and appearance to match your brand.'
+---
+
+# Theming
+
+Dory uses the default Clidey Design theme from `@clidey/ux`. It provides the Paper and Ink surfaces, Signal Blue actions, and light and dark modes. Add `dory.json` overrides to match your product's visual identity.
+
+## Color Configuration
+
+### Brand Colors
+
+```json
+"colors": {
+  "primary": "#6366f1",
+  "light": "#818cf8",
+  "dark": "#4f46e5"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `primary` | Base brand color. Applied to active navigation items, links, and accent elements. |
+| `light` | Lighter shade. Used for hover states and accents in light mode. |
+| `dark` | Darker shade. Used for hover states and accents in dark mode. |
+
+### Extended Colors
+
+For deeper customization, you can control the entire page palette:
+
+```json
+"colors": {
+  "primary": "#F1BF4F",
+  "light": "#F1BF4F",
+  "dark": "#F1BF4F",
+  "background": "#1a1a2e",
+  "surface": "#242440",
+  "surfaceElevated": "#2e2e4a",
+  "foreground": "#f5f5f7",
+  "mutedForeground": "#a0a0b0",
+  "border": "rgba(255, 255, 255, 0.1)",
+  "accent": "#60a5fa"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `background` | Page background color. |
+| `surface` | Header and sidebar background. |
+| `surfaceElevated` | Elevated card/panel backgrounds. |
+| `foreground` | Primary text color. |
+| `mutedForeground` | Secondary/muted text color. |
+| `border` | Border and divider color. |
+| `accent` | Secondary accent color for interactive elements. |
+
+## Theme Mode
+
+Force your docs into dark or light mode regardless of the user's OS preference:
+
+```json
+"theme": {
+  "mode": "dark",
+  "radius": "0.5rem"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `mode` | `"dark"`, `"light"`, or `"system"` (default). Forces a specific color scheme. |
+| `radius` | Base border-radius value for UI elements. |
+
+## Typography
+
+Control heading, body, and code fonts independently:
+
+```json
+"fonts": {
+  "family": "Inter Tight",
+  "source": "https://fonts.gstatic.com/s/intertight/v7/...",
+  "format": "woff2",
+  "heading": {
+    "family": "Fraunces",
+    "source": "https://fonts.gstatic.com/s/fraunces/v31/...",
+    "format": "woff2",
+    "weight": "300 900"
+  },
+  "mono": {
+    "family": "JetBrains Mono",
+    "source": "https://fonts.gstatic.com/s/jetbrainsmono/v18/...",
+    "format": "woff2"
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `family` / `source` / `format` | Body font (applied globally). |
+| `heading` | Optional separate font for h1-h4 headings. |
+| `mono` | Optional separate font for code blocks and inline code. |
+
+<Tip>
+  Combine `theme.mode: "dark"` with custom `background` and `surface` colors to create a dark-themed documentation site that matches your product's look and feel.
+</Tip>
+
+## Dark Mode
+
+Dory automatically follows the user's OS/browser dark mode preference. No configuration required — it works out of the box.
+
+The `light` and `dark` color fields let you fine-tune how your brand color appears on light and dark backgrounds respectively.
+
+<Tip>
+  For best results: choose a `light` shade that's slightly lighter than `primary`, and a `dark` shade that's slightly darker. This ensures good contrast on both backgrounds.
+</Tip>
+
+## Color Palettes
+
+Some well-tested palettes:
+
+<AccordionGroup>
+  <Accordion title="Indigo" icon="palette">
+    ```json
+    "colors": {
+      "primary": "#6366f1",
+      "light": "#818cf8",
+      "dark": "#4f46e5"
+    }
+    ```
+  </Accordion>
+  <Accordion title="Sky Blue" icon="palette">
+    ```json
+    "colors": {
+      "primary": "#0ea5e9",
+      "light": "#38bdf8",
+      "dark": "#0284c7"
+    }
+    ```
+  </Accordion>
+  <Accordion title="Emerald Green" icon="palette">
+    ```json
+    "colors": {
+      "primary": "#10b981",
+      "light": "#34d399",
+      "dark": "#059669"
+    }
+    ```
+  </Accordion>
+  <Accordion title="Rose" icon="palette">
+    ```json
+    "colors": {
+      "primary": "#f43f5e",
+      "light": "#fb7185",
+      "dark": "#e11d48"
+    }
+    ```
+  </Accordion>
+  <Accordion title="Violet" icon="palette">
+    ```json
+    "colors": {
+      "primary": "#8b5cf6",
+      "light": "#a78bfa",
+      "dark": "#7c3aed"
+    }
+    ```
+  </Accordion>
+</AccordionGroup>

package/docs/dory.json

@@ -0,0 +1,129 @@
+{
+  "name": "Dory",
+  "url": "https://dory.clidey.com",
+  "image": "/social-card.png",
+  "version": "1.0.8 · Latest",
+  "copyright": "Clidey",
+  "repository": {
+    "url": "https://github.com/clidey/dory",
+    "branch": "main",
+    "path": "docs"
+  },
+  "description": "Static documentation site generator for modern teams. Build beautiful docs from MDX files.",
+  "seo": {
+    "titleTemplate": "%s — Dory"
+  },
+  "favicon": "./favicon.svg",
+  "fonts": {
+    "family": "Hanken Grotesk",
+    "heading": {
+      "family": "Bricolage Grotesque"
+    },
+    "mono": {
+      "family": "JetBrains Mono"
+    }
+  },
+  "logo": {
+    "light": "./logo/logo.svg",
+    "dark": "./logo/logo.svg"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "introduction",
+              "getting-started/installation",
+              "getting-started/quick-start",
+              "getting-started/automation",
+              "getting-started/whodb-ee-apps",
+              "getting-started/configuration"
+            ]
+          },
+          {
+            "group": "Configuration",
+            "pages": [
+              "configuration/dory-json",
+              "configuration/navigation",
+              "configuration/theming",
+              "configuration/fonts",
+              "configuration/analytics",
+              "configuration/chat",
+              "configuration/internationalization",
+              "configuration/embed"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Components",
+        "groups": [
+          {
+            "group": "Components",
+            "pages": [
+              {
+                "page": "components/overview",
+                "badge": "New"
+              },
+              "components/typography",
+              "components/code-blocks",
+              "components/callouts",
+              "components/cards",
+              "components/accordion",
+              "components/expandable",
+              "components/steps",
+              "components/tables",
+              "components/lists",
+              "components/icons",
+              "components/tags",
+              "components/images",
+              "components/layout",
+              "components/source",
+              "components/mermaid",
+              "components/latex"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "API reference",
+        "groups": [
+          {
+            "group": "API Reference",
+            "pages": [
+              "api-reference/operations/get",
+              "api-reference/operations/create",
+              "api-reference/operations/update",
+              "api-reference/operations/delete"
+            ]
+          },
+          {
+            "group": "Interactive Playgrounds",
+            "pages": [
+              "playgrounds/api-playground",
+              "playgrounds/websocket-playground"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Realtime",
+        "groups": [
+          {
+            "group": "Realtime",
+            "pages": [
+              "api-reference/websocket-operations/receive-chat-message",
+              "api-reference/websocket-operations/send-chat-message",
+              "api-reference/websocket-operations/receive-notifications",
+              "api-reference/websocket-operations/receive-presence-update",
+              "api-reference/websocket-operations/send-presence-update"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/docs/embed-example.html

@@ -0,0 +1,176 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dory Embedded Documentation Example</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 2rem;
+    }
+
+    .container {
+      max-width: 800px;
+      background: white;
+      border-radius: 1rem;
+      padding: 3rem;
+      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+    }
+
+    h1 {
+      font-size: 2.5rem;
+      margin-bottom: 1rem;
+      color: #1f2937;
+    }
+
+    p {
+      font-size: 1.125rem;
+      color: #6b7280;
+      margin-bottom: 2rem;
+      line-height: 1.6;
+    }
+
+    .buttons {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 1rem;
+      margin-bottom: 2rem;
+    }
+
+    button {
+      padding: 0.75rem 1.5rem;
+      font-size: 1rem;
+      font-weight: 600;
+      border: none;
+      border-radius: 0.5rem;
+      cursor: pointer;
+      transition: all 0.2s;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+
+    .btn-primary {
+      background: #3b82f6;
+      color: white;
+    }
+
+    .btn-primary:hover {
+      background: #2563eb;
+      transform: translateY(-2px);
+      box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
+    }
+
+    .btn-secondary {
+      background: #f3f4f6;
+      color: #374151;
+    }
+
+    .btn-secondary:hover {
+      background: #e5e7eb;
+    }
+
+    .code-block {
+      background: #1f2937;
+      color: #f9fafb;
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      overflow-x: auto;
+      margin-bottom: 2rem;
+      font-family: 'Monaco', 'Menlo', monospace;
+      font-size: 0.875rem;
+      line-height: 1.6;
+    }
+
+    .status {
+      padding: 1rem;
+      background: #f0fdf4;
+      border: 1px solid #86efac;
+      border-radius: 0.5rem;
+      color: #166534;
+      margin-bottom: 1rem;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>🐟 Dory Embedded Documentation</h1>
+    <p>
+      This example demonstrates how to embed Dory documentation in your application.
+    </p>
+
+    <div id="status" class="status" style="display: none;"></div>
+
+    <div class="buttons">
+      <button class="btn-primary" onclick="DoryDocs.open()">
+        📚 Open Documentation
+      </button>
+      <button class="btn-secondary" onclick="DoryDocs.open('/features')">
+        ⚡ Open Features
+      </button>
+      <button class="btn-secondary" onclick="DoryDocs.toggle()">
+        🔄 Toggle
+      </button>
+    </div>
+
+    <h2 style="margin-top: 2rem; margin-bottom: 1rem; color: #1f2937;">Integration Code</h2>
+    <div class="code-block">
+&lt;script src="http://localhost:3000/dist/embed.js"&gt;&lt;/script&gt;
+
+&lt;script&gt;
+  DoryDocs.init({
+    baseUrl: 'http://localhost:3000',
+    position: 'right',
+    width: 600,
+    closeOnEscape: true,
+  });
+&lt;/script&gt;
+
+&lt;button onclick="DoryDocs.open()"&gt;Help&lt;/button&gt;
+    </div>
+  </div>
+
+  <!-- Load Dory Embed Script -->
+  <script src="http://localhost:3000/dist/embed.js"></script>
+
+  <!-- Initialize Dory -->
+  <script>
+    window.addEventListener('dory:ready', () => {
+      const status = document.getElementById('status');
+      status.style.display = 'block';
+      status.textContent = '✅ DoryDocs loaded and ready!';
+
+      DoryDocs.init({
+        baseUrl: 'http://localhost:3000',
+        position: 'right',
+        width: 400,
+        theme: 'inherit',
+        closeOnEscape: true,
+        closeOnOverlayClick: true,
+        onOpen: () => {
+          console.log('Docs opened');
+          status.textContent = '📖 Documentation opened';
+        },
+        onClose: () => {
+          console.log('Docs closed');
+          status.textContent = '✅ DoryDocs ready';
+        },
+      });
+    });
+
+    if (window.DoryDocs) {
+      window.dispatchEvent(new Event('dory:ready'));
+    }
+  </script>
+</body>
+</html>

package/docs/favicon.svg

@@ -0,0 +1,18 @@
+<svg width="22" height="24" viewBox="0 0 22 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M21.9941 4.99951C19.9947 3.00079 19.9947 3.00079 16.9956 0.00271368V4.99951H21.9941Z" fill="#92BFFA"/>
+<path d="M7.49782 3.91843C7.49782 4.5155 7.98183 4.99951 8.5789 4.99951H16.9951V0.00271606H8.5789C7.98183 0.00271606 7.49782 0.486733 7.49782 1.0838V3.91843Z" fill="url(#paint0_linear_66_680)"/>
+<path d="M21.9932 5.01123C22.0049 8.20987 21.9983 17.7036 21.9951 21.9995C21.9943 23.1041 21.0977 23.9995 19.9932 23.9995H2C0.895431 23.9995 3.87055e-07 23.1041 0 21.9995V8.59131C0 7.99426 0.48401 7.51028 1.08105 7.51025H3.91797C4.51481 7.51052 4.99902 7.99441 4.99902 8.59131V19.5024H16.9951V5.01123H21.9932Z" fill="url(#paint1_linear_66_680)"/>
+<ellipse cx="12.3217" cy="14.276" rx="1.2973" ry="1.29647" fill="#1967D2"/>
+<path d="M5 0.00634813C5.55157 0.00730227 5.99805 0.454718 5.99805 1.00635V4.01221C5.99805 4.64068 6.29707 5.23179 6.80273 5.60498L7.46777 6.09619C7.81171 6.35003 8.22878 6.48682 8.65625 6.48682H14.4951C15.0472 6.48682 15.4949 6.93475 15.4951 7.48682V16.98C15.4951 17.5322 15.0474 17.98 14.4951 17.98H7.49805C6.94583 17.9799 6.49808 17.5322 6.49805 16.98V8.67139C6.49806 8.23724 6.35689 7.81407 6.0957 7.46729L5.58691 6.79248C5.21558 6.29954 4.63759 6.00515 4.02051 5.99561H1C0.447722 5.9956 0 5.54789 0 4.99561V1.00049C0.000165845 0.447951 0.448441 -4.60729e-05 1.00098 0.00048876L5 0.00634813Z" fill="#FFC236"/>
+<ellipse cx="12.9961" cy="15.505" rx="1" ry="0.999359" fill="#3630C4"/>
+<defs>
+<linearGradient id="paint0_linear_66_680" x1="10.9999" y1="0.00271606" x2="10.9999" y2="23.9995" gradientUnits="userSpaceOnUse">
+<stop stop-color="#528FF4"/>
+<stop offset="1" stop-color="#92BFFA"/>
+</linearGradient>
+<linearGradient id="paint1_linear_66_680" x1="10.9999" y1="0.00271606" x2="10.9999" y2="23.9995" gradientUnits="userSpaceOnUse">
+<stop stop-color="#528FF4"/>
+<stop offset="1" stop-color="#92BFFA"/>
+</linearGradient>
+</defs>
+</svg>