@clidey/dory 1.0.8 → 1.10.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 Dory is and how to get started.'
+lead: 'Dory turns MDX pages into a documentation site with navigation, search, and interactive components.'
+meta:
+  License: MIT
+  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/contributing.mdx

@@ -0,0 +1,47 @@
+---
+title: 'Contributing to Dory'
+description: 'Develop Dory, review its own documentation, and understand the publishing workflow.'
+---
+
+Dory's public README introduces the product. This guide covers work on the repository itself. To create a separate documentation site, use the [quick start](/getting-started/quick-start).
+
+## Run the repository
+
+```bash
+git clone https://github.com/clidey/dory.git
+cd dory
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm dev
+```
+
+Edit Dory's own pages under `docs/`. Keep dependency lifecycle scripts disabled and preserve the repository's dependency integrity and release-age policies.
+
+## Validate changes
+
+```bash
+pnpm test
+node --import tsx --test bin/dependency-overlay.test.mts bin/preview-static.test.mts
+pnpm build
+node bin/dist/dory.js check
+node scripts/verify-component-examples.mjs
+```
+
+The component browser check uses installed Chrome (or `DORY_CHROME_PATH`), measures preview padding and clipping, exercises tabs, and verifies math loading and failure states on desktop and mobile. It saves screenshots and a report under ignored `.dory/component-review/`; inspect these before publishing.
+
+Review browser behavior in light and dark modes. For custom components, verify interactions and focus handling; compilation alone cannot do that.
+
+## Preview the production site
+
+```bash
+pnpm preview --host 127.0.0.1 --port 3188 --strictPort
+```
+
+Open `http://127.0.0.1:3188/dory/`. Review code and the exact generated site before pushing or publishing changes.
+
+## Publish this repository's docs
+
+The documentation workflow validates pull requests and deploys main-branch documentation to `https://clidey.github.io/dory/`. Its canonical URL and path are configured in `docs/dory.json`; GitHub Pages uses GitHub Actions as the publishing source.
+
+Publish only the generated `dist/` artifact. Static Pages hosting includes navigation and search. Documentation chat and HTTP MCP need a separately hosted Dory server; do not put server credentials into static assets.
+
+Imported MDX and component modules are executable source. Review them, build untrusted contributions without secrets or deployment credentials, and deploy reviewed artifacts separately. See the repository security policy for the trust boundary.

package/docs/dory.json

@@ -0,0 +1,136 @@
+{
+  "name": "Dory",
+  "url": "https://clidey.github.io",
+  "image": "/social-card.png",
+  "version": "1.10.0 \u00b7 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 \u2014 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/configuration",
+              "getting-started/custom-components"
+            ]
+          },
+          {
+            "group": "Configuration",
+            "pages": [
+              "configuration/dory-json",
+              "configuration/navigation",
+              "configuration/theming",
+              "configuration/fonts",
+              "configuration/analytics",
+              "configuration/chat",
+              "configuration/internationalization",
+              "configuration/embed"
+            ]
+          },
+          {
+            "group": "Contribute",
+            "pages": [
+              "contributing"
+            ]
+          }
+        ]
+      },
+      {
+        "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"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "basePath": "/dory"
+}