@clidey/dory 1.0.8 → 1.9.0

package/docs/components/lists.mdx

@@ -0,0 +1,134 @@
+---
+title: 'Lists'
+description: 'Styled unordered and ordered lists using standard Markdown or explicit list components.'
+---
+
+# Lists
+
+Dory supports standard Markdown lists and provides explicit `<UnorderedList>`, `<OrderedList>`, and `<ListItem>` components.
+
+## Unordered List
+
+Use standard Markdown syntax:
+
+<Specimen label="- item">
+
+```mdx
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+```
+
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+
+</Specimen>
+
+## Ordered List
+
+<Specimen label="1. item">
+
+```mdx
+1. Clone the repository
+2. Install dependencies
+3. Configure your environment
+4. Run the development server
+```
+
+1. Clone the repository
+2. Install dependencies
+3. Configure your environment
+4. Run the development server
+
+</Specimen>
+
+## Mixed Lists
+
+Combine ordered and unordered lists:
+
+<Specimen label="1. item - nested">
+
+```mdx
+1. Choose an authentication method:
+   - Bearer token (recommended)
+   - API key in query string
+   - Basic authentication
+2. Generate credentials in the dashboard
+3. Include credentials in every request
+```
+
+1. Choose an authentication method:
+   - Bearer token (recommended)
+   - API key in query string
+   - Basic authentication
+2. Generate credentials in the dashboard
+3. Include credentials in every request
+
+</Specimen>
+
+## Explicit Components
+
+Use explicit components when building lists programmatically or with dynamic content:
+
+<Specimen label="&lt;UnorderedList&gt; &lt;ListItem&gt;">
+
+```mdx
+<UnorderedList>
+  <ListItem>Supports 20+ programming languages</ListItem>
+  <ListItem>Copy button on all code blocks</ListItem>
+  <ListItem>Multi-language tab groups</ListItem>
+</UnorderedList>
+```
+
+<UnorderedList>
+  <ListItem>Supports 20+ programming languages</ListItem>
+  <ListItem>Copy button on all code blocks</ListItem>
+  <ListItem>Multi-language tab groups</ListItem>
+</UnorderedList>
+
+</Specimen>
+
+<Specimen label="&lt;OrderedList&gt; &lt;ListItem&gt;">
+
+```mdx
+<OrderedList>
+  <ListItem>Install the Dory CLI</ListItem>
+  <ListItem>Create your dory.json config</ListItem>
+  <ListItem>Write MDX pages</ListItem>
+  <ListItem>Run dory build</ListItem>
+</OrderedList>
+```
+
+<OrderedList>
+  <ListItem>Install the Dory CLI</ListItem>
+  <ListItem>Create your dory.json config</ListItem>
+  <ListItem>Write MDX pages</ListItem>
+  <ListItem>Run dory build</ListItem>
+</OrderedList>
+
+</Specimen>
+
+## Rich List Items
+
+Standard Markdown list items support inline formatting:
+
+<Specimen label="- **bold** *italic* `code`">
+
+```mdx
+- **Bold item** — important information
+- *Italic item* — supplementary detail
+- Item with `inline code` — technical terms
+- Item with a [link](https://dory.clidey.com) — external reference
+```
+
+- **Bold item** — important information
+- *Italic item* — supplementary detail
+- Item with `inline code` — technical terms
+- Item with a [link](https://dory.clidey.com) — external reference
+
+</Specimen>

package/docs/components/mermaid.mdx

@@ -0,0 +1,149 @@
+---
+title: 'Mermaid Diagrams'
+description: 'Render flowcharts, sequence diagrams, ER diagrams, and more using Mermaid syntax in code blocks.'
+---
+
+# Mermaid Diagrams
+
+Use fenced code blocks with the `mermaid` language identifier to render diagrams. Dory automatically detects mermaid syntax and renders it using the [Mermaid](https://mermaid.js.org) library.
+
+**Syntax:**
+
+````mdx
+```mermaid
+flowchart TD
+    A[Start] --> B[End]
+```
+````
+
+## Diagrams
+
+Any code block tagged `mermaid` renders as a diagram using the site palette. It re-renders when the theme changes.
+
+<Specimen label="```mermaid">
+
+````mdx
+```mermaid
+flowchart TD
+    A[Start] --> B{Is data clean?}
+    B -->|Yes| C[Analyze]
+    B -->|No| D[Clean data]
+```
+````
+
+<Tabs>
+  <Tab title="Flowchart">
+
+```mermaid
+flowchart TD
+    A[User writes MDX] --> B[dory build]
+    B --> C{Build successful?}
+    C -->|Yes| D[Static site in dist/]
+    C -->|No| E[Fix errors]
+    E --> B
+    D --> F[Deploy to hosting]
+```
+
+  </Tab>
+  <Tab title="Sequence">
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Database
+
+    Client->>API: POST /api/users
+    API->>Database: INSERT user
+    Database-->>API: user_id
+    API-->>Client: 201 Created
+```
+
+  </Tab>
+  <Tab title="Entity relationship">
+
+```mermaid
+erDiagram
+    USER {
+        string id PK
+        string email
+        string name
+        datetime created_at
+    }
+    WORKSPACE {
+        string id PK
+        string name
+        string owner_id FK
+    }
+    DOCUMENT {
+        string id PK
+        string title
+        string workspace_id FK
+    }
+    USER ||--o{ WORKSPACE : owns
+    WORKSPACE ||--o{ DOCUMENT : contains
+```
+
+  </Tab>
+</Tabs>
+
+</Specimen>
+
+## State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Disconnected
+    Disconnected --> Connecting: connect()
+    Connecting --> Connected: WebSocket open
+    Connecting --> Error: Connection failed
+    Connected --> Disconnected: disconnect()
+    Connected --> Error: Connection lost
+    Error --> Connecting: retry
+    Error --> [*]: give up
+```
+
+## Git Graph
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    branch feature/auth
+    checkout feature/auth
+    commit id: "Add OAuth"
+    commit id: "Add JWT"
+    checkout main
+    merge feature/auth
+    commit id: "v1.0.0"
+```
+
+## Pie Chart
+
+```mermaid
+pie title Documentation Page Types
+    "Getting Started" : 4
+    "Components" : 17
+    "Playgrounds" : 2
+    "Configuration" : 6
+```
+
+## Supported Diagram Types
+
+| Type | Identifier | Description |
+| --- | --- | --- |
+| Flowchart | `flowchart` | Process flows and decision trees |
+| Sequence | `sequenceDiagram` | Interaction between participants |
+| Class | `classDiagram` | Object-oriented class structures |
+| State | `stateDiagram-v2` | State machine transitions |
+| ER Diagram | `erDiagram` | Database entity relationships |
+| Git Graph | `gitGraph` | Git branch history |
+| Gantt | `gantt` | Project timelines |
+| Pie Chart | `pie` | Proportional data |
+
+## Fullscreen Mode
+
+Click any rendered diagram to view it fullscreen. This is useful for complex diagrams that are hard to read at the default size.
+
+<Note>
+  Mermaid diagrams are lazy-loaded. The first render on a page may take a moment while the Mermaid library initializes.
+</Note>

package/docs/components/overview.mdx

@@ -0,0 +1,81 @@
+---
+title: 'Components Overview'
+description: 'All 24 built-in MDX components in Dory — from basic typography to interactive API playgrounds.'
+lead: 'Everything Dory renders from MDX, in one place. Each specimen shows the rendered output, the source behind it, and the props it accepts.'
+meta:
+  Components: 24 built in
+  Theme: From dory.json
+  Updated: 2026-10-21
+---
+
+# Components Overview
+
+Dory ships with **24 built-in MDX components** you can use directly in `.mdx` files without any imports. Components range from basic typography helpers to full interactive API testing tools.
+
+## Content Components
+
+<CardGroup cols={2}>
+  <Card title="Typography" href="/components/typography" icon="type" description="Headings, paragraphs, inline code, and anchor links." />
+  <Card title="Code Blocks" href="/components/code-blocks" icon="code-2" description="Syntax-highlighted code with multi-language tabs and copy button." />
+  <Card title="Callouts" href="/components/callouts" icon="alert-circle" description="Note, Warning, Info, Tip, and Check callout boxes." />
+  <Card title="Cards" href="/components/cards" icon="layout-grid" description="Linked and informational cards in responsive grid layouts." />
+</CardGroup>
+
+## Structure Components
+
+<CardGroup cols={2}>
+  <Card title="Accordion" href="/components/accordion" icon="chevrons-down-up" description="Collapsible content sections with optional icons." />
+  <Card title="Expandable" href="/components/expandable" icon="maximize-2" description="Expandable sections for nested properties and response fields." />
+  <Card title="Steps" href="/components/steps" icon="list-ordered" description="Numbered step-by-step guides with visual connectors." />
+  <Card title="Tables" href="/components/tables" icon="table" description="Responsive tables with styled headers and cells." />
+</CardGroup>
+
+## Media & Visual Components
+
+<CardGroup cols={2}>
+  <Card title="Mermaid Diagrams" href="/components/mermaid" icon="git-branch" description="Flowcharts, sequence diagrams, ER diagrams, and more." />
+  <Card title="LaTeX Math" href="/components/latex" icon="sigma" description="Render mathematical expressions using KaTeX." />
+  <Card title="Images" href="/components/images" icon="image" description="Clickable images with fullscreen modal overlay." />
+  <Card title="Icons" href="/components/icons" icon="star" description="Inline icons from the WhoDB suite." />
+</CardGroup>
+
+## Utility Components
+
+<CardGroup cols={2}>
+  <Card title="Lists" href="/components/lists" icon="list" description="Styled unordered and ordered lists." />
+  <Card title="Tags" href="/components/tags" icon="tag" description="HTTP method badges and custom color tags." />
+  <Card title="Layout" href="/components/layout" icon="columns-2" description="Row and Col for multi-column grid layouts." />
+  <Card title="Source Links" href="/components/source" icon="git-pull-request" description="Direct links to source code on GitHub, GitLab, or Bitbucket." />
+</CardGroup>
+
+## Interactive Playgrounds
+
+<CardGroup cols={2}>
+  <Card title="API Playground" href="/playgrounds/api-playground" icon="play-circle" description="Interactive HTTP request testing with headers, auth, and response display." />
+  <Card title="WebSocket Playground" href="/playgrounds/websocket-playground" icon="activity" description="Live WebSocket connection tester with message history." />
+</CardGroup>
+
+## Using Components
+
+All components are available in `.mdx` files without any imports:
+
+```mdx
+---
+title: 'My Page'
+---
+
+# My Page
+
+<Note>
+  This is a note callout — no import needed.
+</Note>
+
+<CardGroup cols={2}>
+  <Card title="Getting Started" icon="rocket" description="Set up your project." />
+  <Card title="Configuration" icon="settings" description="Customize your site." />
+</CardGroup>
+```
+
+<Note>
+  All components are built into Dory. You never need to install or import anything — just use them directly in your pages.
+</Note>

package/docs/components/source.mdx

@@ -0,0 +1,130 @@
+---
+title: 'Source Links'
+description: 'Link directly to source code files on GitHub, GitLab, or Bitbucket with optional line ranges.'
+---
+
+# Source Links
+
+The `<Source>` component renders styled links that point directly to source code on your repository host. It supports GitHub, GitLab, and Bitbucket with optional line range anchors.
+
+## Basic Usage
+
+Link to a single file:
+
+<Specimen label="&lt;Source&gt;">
+
+```mdx
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[{ path: "src/mdx/code.tsx" }]}
+/>
+```
+
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[{ path: "src/mdx/code.tsx" }]}
+/>
+
+</Specimen>
+
+## Multiple Files
+
+Link to multiple files at once:
+
+<Specimen label="&lt;Source&gt;">
+
+```mdx
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[
+    { path: "src/mdx/accordion.tsx" },
+    { path: "src/mdx/callout.tsx" },
+    { path: "src/mdx/card.tsx" }
+  ]}
+/>
+```
+
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[
+    { path: "src/mdx/accordion.tsx" },
+    { path: "src/mdx/callout.tsx" },
+    { path: "src/mdx/card.tsx" }
+  ]}
+/>
+
+</Specimen>
+
+## With Line Range
+
+Link to a specific range of lines:
+
+<Specimen label="&lt;Source&gt;">
+
+```mdx
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[{ path: "src/mdx/code.tsx", range: "1-50" }]}
+/>
+```
+
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[{ path: "src/mdx/code.tsx", range: "1-50" }]}
+/>
+
+</Specimen>
+
+## Platform Support
+
+| Platform | URL Format | Line Anchor Format |
+| --- | --- | --- |
+| GitHub | `github.com/owner/repo` | `#L{start}-L{end}` |
+| GitLab | `gitlab.com/owner/repo` | `#L{range}` |
+| Bitbucket | `bitbucket.org/owner/repo` | `#lines-{start}:{end}` |
+
+Dory automatically detects the platform from the URL and formats the link accordingly.
+
+## Use Case: Inline Source References
+
+Source links are ideal for documentation that references implementation details:
+
+<Specimen label="&lt;Source&gt;">
+
+```mdx
+The MDX preprocessing pipeline is defined here:
+
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[{ path: "src/mdx/processor.ts" }]}
+/>
+
+This file is the single source of truth for MDX compilation settings.
+```
+
+The MDX preprocessing pipeline is defined here:
+
+<Source
+  url="https://github.com/clidey/dory"
+  branch="main"
+  paths={[{ path: "src/mdx/processor.ts" }]}
+/>
+
+This file is the single source of truth for MDX compilation settings.
+
+</Specimen>
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | `string` | — | Base URL of the repository (e.g. `https://github.com/owner/repo`). |
+| `branch` | `string` | `"main"` | Branch name. |
+| `paths` | `Array<{ path: string, range?: string }>` | — | Files to link. `range` format: `"start-end"` (e.g. `"10-50"`). |

package/docs/components/steps.mdx

@@ -0,0 +1,122 @@
+---
+title: 'Steps'
+description: 'Numbered step-by-step guides with visual connectors between steps.'
+---
+
+# Steps
+
+Use `<Steps>` and `<Step>` to present multi-step processes with numbered indicators and a vertical connection line.
+
+## Basic Steps
+
+<Specimen label="&lt;Steps&gt; &lt;Step&gt;">
+
+```mdx
+<Steps>
+  <Step title="Install Dory">
+    Install the CLI globally with npm or pnpm.
+  </Step>
+  <Step title="Create dory.json">
+    Create a configuration file in your docs directory.
+  </Step>
+  <Step title="Write your first page">
+    Create introduction.mdx with frontmatter and content.
+  </Step>
+  <Step title="Build and preview">
+    Run the CLI to build and preview your site.
+  </Step>
+</Steps>
+```
+
+<Steps>
+  <Step title="Install Dory">
+    Install the CLI globally: `npm install -g @clidey/dory`
+  </Step>
+  <Step title="Create dory.json">
+    Create a configuration file with your site name, colors, and navigation structure.
+  </Step>
+  <Step title="Write your first page">
+    Create `introduction.mdx` with a frontmatter block (`title`, `description`) and your content.
+  </Step>
+  <Step title="Build and preview">
+    Run `dory build` then `dory preview` to see your site at `http://localhost:3000`.
+  </Step>
+</Steps>
+
+</Specimen>
+
+## Steps with Rich Content
+
+Each `<Step>` supports full MDX content including callouts and inline code:
+
+<Specimen label="&lt;Steps&gt; &lt;Step&gt;">
+
+```mdx
+<Steps>
+  <Step title="Generate an API key">
+    Log in to your dashboard and navigate to Settings > API Keys.
+
+    Store the key securely — it is shown only once.
+  </Step>
+  <Step title="Configure authentication">
+    Add your API key to the Authorization header on every request.
+  </Step>
+  <Step title="Make your first request">
+    Test the connection with a simple GET request to verify your credentials.
+  </Step>
+</Steps>
+```
+
+<Steps>
+  <Step title="Generate an API key">
+    Log in to your dashboard and navigate to **Settings → API Keys**.
+
+    <Warning>
+      API keys are shown only once. Copy it immediately and store it securely.
+    </Warning>
+  </Step>
+  <Step title="Configure authentication">
+    Add your API key to the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`
+  </Step>
+  <Step title="Make your first request">
+    Test the connection with `GET /api/v1/me` to verify your credentials work.
+
+    <Check>
+      If you see your user object, authentication is working correctly.
+    </Check>
+  </Step>
+</Steps>
+
+</Specimen>
+
+## Authentication Setup Example
+
+<Steps>
+  <Step title="Create an account">
+    Sign up at the dashboard. Verify your email to activate your account.
+  </Step>
+  <Step title="Install the SDK">
+    Install the client library for your language: `npm install @example/sdk`
+  </Step>
+  <Step title="Initialize the client">
+    Import and configure the SDK with your API key from the dashboard.
+  </Step>
+  <Step title="Make your first API call">
+    Call any endpoint to verify the integration is working correctly.
+  </Step>
+</Steps>
+
+## Props Reference
+
+### Steps Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `ReactNode` | One or more `Step` components. |
+
+### Step Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Step heading shown next to the step number. |
+| `children` | `ReactNode` | Step content. Supports full MDX. |