@clidey/dory 1.0.8 → 1.10.0

package/docs/components/tables.mdx

@@ -0,0 +1,114 @@
+---
+title: 'Tables'
+description: 'Responsive tables with styled headers and cells using standard Markdown or Table components.'
+---
+
+# Tables
+
+Dory renders tables from standard Markdown syntax and also provides `<Table>`, `<Th>`, and `<Td>` components for programmatic use.
+
+## Markdown Tables
+
+Use standard Markdown table syntax:
+
+<Specimen label="| Name | Type | … |">
+
+```mdx
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | Unique identifier. |
+| `name` | `string` | Yes | Display name. |
+| `email` | `string` | No | Email address. |
+| `created_at` | `string` | No | ISO 8601 timestamp. |
+```
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | Unique identifier. |
+| `name` | `string` | Yes | Display name. |
+| `email` | `string` | No | Email address. |
+| `created_at` | `string` | No | ISO 8601 timestamp. |
+
+</Specimen>
+
+## Alignment
+
+Use colons in the separator row to control column alignment:
+
+<Specimen label="| Left | Center | … |">
+
+```mdx
+| Left | Center | Right |
+| :--- | :---: | ---: |
+| text | text | text |
+| longer text | longer text | longer text |
+```
+
+| Left | Center | Right |
+| :--- | :---: | ---: |
+| text | text | text |
+| longer text | longer text | longer text |
+
+</Specimen>
+
+## Configuration Reference Table
+
+Tables work well for configuration references:
+
+<Specimen label="| Field | Type | … |">
+
+```mdx
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | — | Site name shown in the header. |
+| `colors.primary` | `string` | `#6366f1` | Brand primary color (hex). |
+| `fonts.family` | `string` | System font | Font family name. |
+| `navigation.tabs` | `array` | `[]` | Navigation tab definitions. |
+```
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | — | Site name shown in the header. |
+| `colors.primary` | `string` | `#6366f1` | Brand primary color (hex). |
+| `fonts.family` | `string` | System font | Font family name. |
+| `navigation.tabs` | `array` | `[]` | Navigation tab definitions. |
+
+</Specimen>
+
+## HTTP Status Code Table
+
+<Specimen label="| Status | Code | … |">
+
+```mdx
+| Status | Code | Description |
+| --- | --- | --- |
+| OK | `200` | Request succeeded. |
+| Created | `201` | Resource created successfully. |
+| Bad Request | `400` | Invalid parameters or missing required fields. |
+| Unauthorized | `401` | Missing or invalid authentication token. |
+| Forbidden | `403` | Authenticated but lacking permission. |
+| Not Found | `404` | Resource does not exist. |
+| Rate Limited | `429` | Too many requests. Check `Retry-After` header. |
+| Server Error | `500` | Unexpected server error. |
+```
+
+| Status | Code | Description |
+| --- | --- | --- |
+| OK | `200` | Request succeeded. |
+| Created | `201` | Resource created successfully. |
+| Bad Request | `400` | Invalid parameters or missing required fields. |
+| Unauthorized | `401` | Missing or invalid authentication token. |
+| Forbidden | `403` | Authenticated but lacking permission. |
+| Not Found | `404` | Resource does not exist. |
+| Rate Limited | `429` | Too many requests. Check `Retry-After` header. |
+| Server Error | `500` | Unexpected server error. |
+
+</Specimen>
+
+## Long Tables
+
+Tables are wrapped in a horizontally scrollable container, so wide tables work on mobile without breaking the layout.
+
+<Note>
+  Tables are automatically wrapped in `overflow-x-auto` — wide tables scroll horizontally rather than overflowing the page.
+</Note>

package/docs/components/tags.mdx

@@ -0,0 +1,179 @@
+---
+title: 'Tags'
+description: 'HTTP method badges and custom color tags for labeling content.'
+---
+
+# Tags
+
+The `<Tag>` component renders colored badges. It has built-in support for HTTP methods and supports custom colors.
+
+## HTTP Method Tags
+
+Tags automatically apply the correct color for HTTP methods:
+
+<Specimen label="&lt;Tag&gt;">
+
+```mdx
+<Tag>GET</Tag>
+<Tag>POST</Tag>
+<Tag>PUT</Tag>
+<Tag>DELETE</Tag>
+```
+
+<Tag>GET</Tag> <Tag>POST</Tag> <Tag>PUT</Tag> <Tag>DELETE</Tag>
+
+</Specimen>
+
+## HTTP Method Colors
+
+| Method | Color |
+| --- | --- |
+| `GET` | Sky (blue) |
+| `POST` | Emerald (green) |
+| `PUT` | Amber (orange) |
+| `DELETE` | Rose (red) |
+
+## Custom Colors
+
+Use the `color` prop for non-HTTP-method tags:
+
+<Specimen label="&lt;Tag&gt;">
+
+```mdx
+<Tag color="sky">Beta</Tag>
+<Tag color="yellow">New</Tag>
+<Tag color="rose">Deprecated</Tag>
+<Tag color="emerald">Stable</Tag>
+<Tag color="zinc">v1.2.2</Tag>
+```
+
+<Tag color="sky">Beta</Tag> <Tag color="yellow">New</Tag> <Tag color="rose">Deprecated</Tag> <Tag color="emerald">Stable</Tag> <Tag color="zinc">v1.2.2</Tag>
+
+</Specimen>
+
+## Tag Variants
+
+The `variant` prop controls padding size:
+
+<Specimen label="&lt;Tag&gt;">
+
+```mdx
+<Tag variant="medium">Default size</Tag>
+<Tag variant="small">Compact</Tag>
+```
+
+<Tag variant="medium">Default size</Tag> <Tag variant="small">Compact</Tag>
+
+</Specimen>
+
+## Tags in API Reference
+
+Tags are commonly used in API reference documentation to label HTTP methods:
+
+<Specimen label="**GET** `path`">
+
+```mdx
+**GET** `/api/users` — Retrieve a list of all users.
+
+**POST** `/api/users` — Create a new user.
+
+**DELETE** `/api/users/:id` — Permanently delete a user.
+```
+
+**GET** `/api/users` — Retrieve a list of all users.
+
+**POST** `/api/users` — Create a new user.
+
+**DELETE** `/api/users/:id` — Permanently delete a user.
+
+</Specimen>
+
+Or with the Tag component on its own line:
+
+<Specimen label="&lt;Tag&gt;">
+
+```mdx
+<Tag>GET</Tag>
+
+`/api/users` — Retrieve a list of all users.
+```
+
+<Tag>GET</Tag>
+
+`/api/users` — Retrieve a list of all users.
+
+</Specimen>
+
+## Version and Status Tags
+
+<Specimen label="&lt;Tag&gt;">
+
+```mdx
+**Authentication** <Tag color="emerald">v2.0</Tag>
+
+The new authentication system uses OAuth 2.0 with PKCE.
+```
+
+**Authentication** <Tag color="emerald">v2.0</Tag>
+
+The new authentication system uses OAuth 2.0 with PKCE.
+
+</Specimen>
+
+<Specimen label="&lt;Tag&gt;">
+
+```mdx
+**Legacy Auth** <Tag color="rose">Deprecated</Tag>
+
+The API key authentication method is deprecated and will be removed in v3.0.
+```
+
+**Legacy Auth** <Tag color="rose">Deprecated</Tag>
+
+The API key authentication method is deprecated and will be removed in v3.0.
+
+</Specimen>
+
+## Chips
+
+`<Chip>` is a pill with a brand-colored dot for short, scannable lists such as supported platforms. Wrap several in `<ChipGroup>` so they flow in rows.
+
+<Specimen label="&lt;ChipGroup&gt; &lt;Chip&gt;">
+
+```mdx
+<ChipGroup>
+  <Chip>Postgres</Chip>
+  <Chip>MySQL</Chip>
+  <Chip href="/components/cards">SQLite</Chip>
+</ChipGroup>
+```
+
+<ChipGroup>
+  <Chip>Postgres</Chip>
+  <Chip>MySQL</Chip>
+  <Chip>MariaDB</Chip>
+  <Chip>SQLite</Chip>
+  <Chip>MongoDB</Chip>
+  <Chip>Redis</Chip>
+  <Chip>ClickHouse</Chip>
+  <Chip>ElasticSearch</Chip>
+  <Chip>DuckDB</Chip>
+</ChipGroup>
+
+<SpecimenProps>
+
+<Prop name="children" type="string">Chip label.</Prop>
+<Prop name="href" type="string">Makes the chip a link.</Prop>
+
+</SpecimenProps>
+
+</Specimen>
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `string` | — | Tag label text (e.g. `"GET"`, `"Beta"`). |
+| `color` | `string` | Auto-detected | Badge color: `emerald`, `sky`, `amber`, `rose`, `zinc`, `yellow`. HTTP methods auto-apply color. |
+| `variant` | `string` | `'medium'` | Padding size: `medium` or `small`. |
+| `className` | `string` | — | Additional CSS classes. |

package/docs/components/typography.mdx

@@ -0,0 +1,185 @@
+---
+title: 'Typography'
+description: 'Headings, paragraphs, inline code, anchors, and layout helpers for text-heavy pages.'
+---
+
+# Typography
+
+Dory provides standard Markdown typography plus a few layout helpers for rich text pages.
+
+## Headings
+
+Markdown headings map to the display scale. Inline formatting covers emphasis, code, links, keys and highlights.
+
+<Specimen label="# ## ### ####">
+
+```mdx
+# Heading 1
+## Heading 2
+### Heading 3
+#### Heading 4
+
+**Bold**, *italic*, `inline code`, [a link](https://clidey.github.io/dory/), <kbd>⌘K</kbd>, and <mark>a highlight</mark>.
+
+> Blockquotes hold asides and quotes.
+```
+
+<TypeScale />
+
+**Bold**, *italic*, `inline code`, [a link](https://clidey.github.io/dory/), <kbd>⌘K</kbd>, and <mark>a highlight</mark>.
+
+> Blockquotes hold asides and quotes.
+
+</Specimen>
+
+---
+
+## Paragraphs
+
+Standard Markdown paragraphs are styled with consistent spacing.
+
+This is a paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+This is a second paragraph, separated by a blank line.
+
+---
+
+## Inline Code
+
+Use backticks for inline `code`. This is styled distinctly from surrounding text.
+
+<Specimen label="`code`">
+
+```mdx
+Use backticks for inline `code`.
+```
+
+Use backticks for inline `code`.
+
+</Specimen>
+
+---
+
+## Links
+
+Use standard Markdown link syntax for hyperlinks:
+
+<Specimen label="[link](url)">
+
+```mdx
+[Visit the Dory site](https://clidey.github.io/dory/)
+```
+
+[Visit the Dory site](https://clidey.github.io/dory/)
+
+</Specimen>
+
+---
+
+## Horizontal Rule
+
+Use `---` for a horizontal divider:
+
+<Specimen label="---">
+
+```mdx
+---
+```
+
+---
+
+</Specimen>
+
+## Line Break
+
+Use `<br/>` to insert explicit line breaks without starting a new paragraph:
+
+<Specimen label="&lt;br/&gt;">
+
+```mdx
+First line<br/>Second line on a new line
+```
+
+First line<br/>Second line on a new line
+
+</Specimen>
+
+---
+
+## Bold and Italic
+
+<Specimen label="**bold** *italic*">
+
+```mdx
+**Bold text** and *italic text* and ***bold italic***.
+```
+
+**Bold text** and *italic text* and ***bold italic***.
+
+</Specimen>
+
+---
+
+## Row and Col
+
+Use `<Row>` and `<Col>` to create multi-column layouts for prose content:
+
+<Specimen label="&lt;Row&gt; &lt;Col&gt;">
+
+```mdx
+<Row>
+  <Col>
+    **Left column content**
+
+    This text appears on the left side.
+  </Col>
+  <Col>
+    **Right column content**
+
+    This text appears on the right side.
+  </Col>
+</Row>
+```
+
+<Row>
+  <Col>
+    **Left column content**
+
+    This text appears on the left side.
+  </Col>
+  <Col>
+    **Right column content**
+
+    This text appears on the right side.
+  </Col>
+</Row>
+
+</Specimen>
+
+### Row Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cols` | `number` | `1` | Number of columns in the grid. |
+| `className` | `string` | — | Additional CSS classes. |
+
+### Col Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sticky` | `boolean` | `false` | Makes the column sticky on large screens (`xl:sticky top-24`). Useful for code/example columns. |
+| `rows` | `number` | `1` | Number of CSS grid rows this column spans. |
+| `gap` | `number` | `4` | Spacing between items inside the column. |
+
+### Sticky Column Example
+
+```mdx
+<Row>
+  <Col>
+    Long prose content that scrolls...
+  </Col>
+  <Col sticky>
+    Code example that stays visible while scrolling.
+  </Col>
+</Row>
+```

package/docs/configuration/analytics.mdx

@@ -0,0 +1,45 @@
+---
+title: Analytics
+description: Send documentation traffic, searches, feedback, engagement, and AI crawler requests to PostHog.
+---
+
+# Analytics
+
+Dory sends documentation analytics to your PostHog project. There is no Dory analytics account, dashboard, admin password, or local analytics database. If PostHog is not configured, Dory does not collect analytics.
+
+## Connect PostHog
+
+Add your PostHog project key to `dory.json`:
+
+```json
+"analytics": {
+  "posthog": {
+    "token": "phc_your_project_key",
+    "apiHost": "https://us.i.posthog.com"
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `posthog.token` | Public PostHog project key, usually beginning with `phc_`. |
+| `posthog.apiHost` | Your PostHog ingestion host. Defaults to the US cloud host; set your own region or self-hosted host when needed. |
+
+Run `dory build` and redeploy after changing `dory.json`. View the resulting events and reports in PostHog. The project key is embedded in the public site; do not put a private PostHog API key in `dory.json`.
+
+If your host sets a Content Security Policy and you use a custom `apiHost`, allow that host's event endpoint in `connect-src` and its script asset origin in `script-src`.
+
+## What is sent
+
+| Source | Events |
+| --- | --- |
+| Browser | Page views and page leaves; `docs_search`, `docs_search_result_clicked`, `docs_page_feedback`, `docs_code_copied`, `docs_page_engaged`, and `docs_chat_*` interaction events. |
+| Dory Node server | `docs_page_request` for successful documentation page requests and `docs_ai_request` for requests from recognized AI crawler user agents. |
+
+Browser events work on static hosting, including a CDN. Server request events require documentation requests to reach the Dory Node server; a CDN cache hit or direct static-file response cannot be counted by that server. Browser page views and server page requests are separate event types, so use the one that matches the report you want.
+
+Use PostHog's browser `$pageview` events for visitor counts. Server request events use a new anonymous ID per request to avoid sending reader identifiers, so their unique-user count does not represent unique readers.
+
+Dory does not send chat question or answer text, conversation history, or copied code. Search terms are shortened and likely credentials are redacted before capture. Search terms can still contain personal information, so configure consent and retention in PostHog for your site. AI crawler names come from user-agent headers and are unverified.
+
+PostHog browser tracking is disabled during local Vite development so authoring activity does not appear in production reports.

package/docs/configuration/chat.mdx

@@ -0,0 +1,59 @@
+---
+title: Documentation chat
+description: Add a cited documentation assistant with server-side credentials and strict request limits.
+---
+
+# Documentation chat
+
+Dory can add an **Ask Dory** assistant to your site. It is optional. The browser sends questions to a same-origin `/api/chat` endpoint; only the server calls your model provider. Answers include links to the documentation sections used as sources. When the docs have no matching source, the assistant says it cannot find the answer.
+
+## Configure a model
+
+Set these environment variables on the server running `dory dev` or `dory preview`:
+
+```bash
+DORY_CHAT_API_KEY=your-server-only-key
+DORY_CHAT_MODEL=gpt-6-luna
+# Optional: an OpenAI-compatible provider endpoint; defaults to https://api.openai.com/v1
+DORY_CHAT_BASE_URL=https://api.openai.com/v1
+```
+
+If your existing `.env` uses `OPENAI_API_KEY`, Dory accepts that as a fallback. Set `DORY_CHAT_MODEL` as well; no model is chosen silently.
+
+The chosen provider must support the OpenAI-compatible `/chat/completions` API and `max_completion_tokens`. Keep the key in your server's secret manager or an uncommitted `.env` file. **Do not use a `VITE_` prefix** for the key: Vite exposes variables with that prefix to browser code. Dory never puts `DORY_CHAT_API_KEY` in the generated site or sends it to the browser.
+
+Run `dory dev` while writing, or `dory build && dory preview` to serve the built site with chat. A static-file host cannot execute `/api/chat`; if you deploy `dist/` to one, put a compatible server endpoint behind the same path. Dory hides the chat button when no backend is configured.
+
+When enabled, Ask Dory appears in the documentation search dialog. Readers can switch to chat, choose a suggested question, or select the Ask Dory result above page matches to ask their current search query. Supported answers include citations and documentation-focused follow-up questions. If a question is outside the published docs, Ask Dory says so without attaching an unrelated source and suggests topics from your configured questions instead.
+
+To customize the suggested questions for your site, add this optional section to `dory.json`:
+
+```json
+"chat": {
+  "suggestedQuestions": [
+    "How do I install the product?",
+    "What should I try first?",
+    "Explain this page"
+  ]
+}
+```
+
+Without this section, Dory suggests questions based on your site name. Keep provider keys in the server environment, never in `dory.json`.
+
+## Limits and security
+
+The backend rejects cross-origin requests, oversized messages, long conversation histories, and requests beyond its limits. The defaults are deliberately conservative:
+
+When using `dory dev` on `localhost`, `127.0.0.1`, or `::1`, Dory skips the per-minute and daily request quotas so you can iterate on chat locally. The concurrent-call guard still applies. `dory preview` and deployed servers keep the quotas below.
+
+| Environment variable | Default | Purpose |
+| --- | ---: | --- |
+| `DORY_CHAT_PER_MINUTE` | `3` | Requests per IP per minute |
+| `DORY_CHAT_PER_IP_DAY` | `20` | Requests per IP per day |
+| `DORY_CHAT_GLOBAL_DAY` | `100` | Requests across the server per day |
+| `DORY_CHAT_MAX_CONCURRENT` | `2` | Simultaneous model calls across the server |
+| `DORY_CHAT_MAX_OUTPUT_TOKENS` | `500` | Maximum model output tokens |
+
+Each request has a 20-second provider timeout. A question can contain at most 600 characters, and at most six previous turns are accepted. The limits above apply **per Node process**; for multiple replicas, enforce shared limits at your reverse proxy or edge as well. Dory uses the connection IP, not an untrusted `X-Forwarded-For` header. If you put the server behind a reverse proxy, configure limits there using its verified client IP.
+
+The server retrieves relevant MDX sections and gives only those excerpts to the model. It validates returned source IDs before showing an answer. Model output can still be imperfect, so keep examples and API facts reviewed and use `dory check` in CI.