@clidey/dory 1.0.8 → 1.9.0

package/docs/features.mdx

@@ -0,0 +1,440 @@
+---
+title: 'Features'
+description: 'Overview of available components and features'
+---
+
+## Headings Examples
+
+```mdx
+# Heading 1
+```
+# Heading 1
+
+```mdx
+## Heading 2
+```
+# Heading 2
+
+```mdx
+### Heading 3
+```
+# Heading 3
+```mdx
+#### Heading 4
+```
+# Heading 4
+```mdx
+##### Heading 5
+```
+# Heading 5
+```mdx
+###### Heading 6
+```
+# Heading 6
+
+<br />
+
+## Lists Examples
+
+```mdx
+- List item 1
+- List item 2
+- List item 3
+```
+
+- List item 1
+- List item 2
+- List item 3
+
+```mdx
+1. List item 1
+2. List item 2
+3. List item 3
+```
+
+1. List item 1
+2. List item 2
+3. List item 3
+
+
+
+<br />
+
+### Images
+
+```mdx
+<img src="./assets/dory.jpeg" alt="Example image" className="object-cover w-64 h-64" />
+```
+
+<img src="./assets/dory.jpeg" alt="Example image" className="object-cover w-64 h-64" />
+
+
+<br />
+<br />
+<br />
+
+## Code Components
+
+### Code Block
+```typescript
+function example() {
+  return "Hello World";
+}
+```
+
+### Code Group Block
+
+<CodeGroup>
+```typescript
+function example(): string {
+  return "Hello World";
+}
+```
+```javascript
+function example() {
+  return "Hello World";
+}
+```
+</CodeGroup>
+
+
+<br />
+<br />
+<br />
+
+
+## Interactive Components
+
+### Mermaid
+
+```mdx
+mermaid
+graph TD
+
+  %% Main Start
+  Start([Start Process]) --> Validate[Validate Input]
+
+  %% Decision Point
+  Validate -->|Valid| ProcessData{Is Data Clean?}
+  Validate -->|Invalid| Error[Show Error Message]
+
+  %% Clean Data Branch
+  ProcessData -->|Yes| Clean[Clean Data]
+  Clean --> Analyze[Analyze Data]
+
+  %% Dirty Data Branch
+  ProcessData -->|No| Notify[Notify User]
+  Notify --> Wait[Wait for Input]
+  Wait --> Validate
+
+  %% Parallel Branches After Analysis
+  Analyze --> Split1 & Split2
+
+  subgraph Parallel Tasks
+    Split1[Generate Report] --> Merge
+    Split2[Update Dashboard] --> Merge
+  end
+
+  Merge --> Decision2{Is More Input Needed?}
+  Decision2 -->|Yes| WaitMore[Wait for More Input]
+  WaitMore --> Validate
+  Decision2 -->|No| End([End Process])
+
+  %% Style and Class Definitions
+  classDef decision fill:#f9f,stroke:#333,stroke-width:2px;
+  class ProcessData,Decision2 decision;
+
+```
+
+<strong>
+<p>Note: Mermaid should be inside a code block with type "mermaid"</p>
+</strong>
+
+```mermaid
+graph TD
+
+  %% Main Start
+  Start([Start Process]) --> Validate[Validate Input]
+
+  %% Decision Point
+  Validate -->|Valid| ProcessData{Is Data Clean?}
+  Validate -->|Invalid| Error[Show Error Message]
+
+  %% Clean Data Branch
+  ProcessData -->|Yes| Clean[Clean Data]
+  Clean --> Analyze[Analyze Data]
+
+  %% Dirty Data Branch
+  ProcessData -->|No| Notify[Notify User]
+  Notify --> Wait[Wait for Input]
+  Wait --> Validate
+
+  %% Parallel Branches After Analysis
+  Analyze --> Split1 & Split2
+
+  subgraph Parallel Tasks
+    Split1[Generate Report] --> Merge
+    Split2[Update Dashboard] --> Merge
+  end
+
+  Merge --> Decision2{Is More Input Needed?}
+  Decision2 -->|Yes| WaitMore[Wait for More Input]
+  WaitMore --> Validate
+  Decision2 -->|No| End([End Process])
+
+  %% Style and Class Definitions
+  classDef decision fill:#f9f,stroke:#333,stroke-width:2px;
+  class ProcessData,Decision2 decision;
+
+```
+
+### Accordion
+
+```mdx
+<AccordionGroup>
+  <Accordion title="First Section" icon="FileText">
+    This is the content of the first accordion section.
+  </Accordion>
+  <Accordion title="Second Section" icon="Code">
+    This is the content of the second accordion section.
+  </Accordion>
+</AccordionGroup>
+```
+
+<AccordionGroup>
+  <Accordion title="First Section" icon="FileText">
+    This is the content of the first accordion section.
+  </Accordion>
+  <Accordion title="Second Section" icon="Code">
+    This is the content of the second accordion section.
+  </Accordion>
+</AccordionGroup>
+
+### Callouts
+
+```mdx
+<Note>
+  This is a note callout with important information.
+</Note>
+```
+
+<Note>
+  This is a note callout with important information.
+</Note>
+
+```mdx
+<Warning>
+  This is a warning callout for critical information.
+</Warning>
+```
+
+<Warning>
+  This is a warning callout for critical information.
+</Warning>
+
+```mdx
+<Info>
+  This is an info callout for general information.
+</Info>
+```
+
+<Info>
+  This is an info callout for general information.
+</Info>
+
+```mdx
+<Tip>
+  This is a tip callout for helpful suggestions.
+</Tip>
+```
+
+<Tip>
+  This is a tip callout for helpful suggestions.
+</Tip>
+
+```mdx
+<Check>
+  This is a check callout for completed items.
+</Check>
+```
+
+<Check>
+  This is a check callout for completed items.
+</Check>
+
+
+<br />
+
+### Cards
+```mdx
+<CardGroup cols={2}>
+  <Card 
+    title="Example Card" 
+    description="This is an example card component with an icon and title."
+    icon="FileText"
+    href="#"
+  />
+  <Card 
+    title="Another Card" 
+    description="This is another example card with different content."
+    icon="Code"
+    href="#"
+  />
+</CardGroup>
+```
+
+<CardGroup cols={2}>
+  <Card 
+    title="Example Card" 
+    description="This is an example card component with an icon and title."
+    icon="FileText"
+    href="#"
+  />
+  <Card 
+    title="Another Card" 
+    description="This is another example card with different content."
+    icon="Code"
+    href="#"
+  />
+</CardGroup>
+
+<br />
+
+### Expandable
+
+```mdx
+<Expandable title="Click to Expand">
+  This is an expandable section that can be toggled.
+</Expandable>
+```
+
+<Expandable title="Click to Expand">
+  This is an expandable section that can be toggled.
+</Expandable>
+
+### Source
+
+```mdx
+<Source url="https://github.com/clidey/dory" paths={[
+  { path: "src/mdx/source.tsx", range: "1-46" },
+  { path: "docs/features.mdx", range: "318-322" },
+]} />
+```
+
+<Source url="https://github.com/clidey/dory" paths={[
+  { path: "src/mdx/source.tsx", range: "1-46" },
+  { path: "docs/features.mdx", range: "318-322" },
+]} />
+
+<br />
+<br />
+<br />
+
+
+## Special Components
+
+### Grids
+
+#### Rows
+```mdx
+<Row cols={2}>
+  <Icon icon="FileText" />
+  <Icon icon="CheckCircle" />
+</Row>
+```
+
+<Row cols={2}>
+  <Icon icon="FileText" />
+  <Icon icon="CheckCircle" />
+</Row>
+
+<br />
+
+#### Columns
+
+```mdx
+<Col>
+  <Icon icon="FileText" />
+  <Icon icon="FileText" />
+</Col>
+```
+
+<Col>
+  <Icon icon="FileText" />
+  <Icon icon="FileText" />
+</Col>
+
+<br />
+<br />
+<br />
+
+### Latex
+
+```mdx
+<Latex>
+E = mc^2
+</Latex>
+```
+
+<Latex>
+E = mc^2
+</Latex>
+
+<br />
+<br />
+<br />
+
+### Tables
+
+```mdx
+| Property | Description                           |
+| -------- | ------------------------------------- |
+| Name     | Full name of user                     |
+| Age      | Reported age                          |
+| Joined   | Whether the user joined the community |
+```
+
+| Property | Description                           |
+| -------- | ------------------------------------- |
+| Name     | Full name of user                     |
+| Age      | Reported age                          |
+| Joined   | Whether the user joined the community |
+
+
+### Steps
+
+```mdx
+<Steps>
+  <Step title="First Step">
+  This is the first step in the process.
+  </Step>
+  <Step title="Second Step">
+  This is the second step in the process.
+  </Step>
+</Steps>
+```
+
+<Steps>
+  <Step title="First Step">
+  This is the first step in the process.
+  </Step>
+  <Step title="Second Step">
+  This is the second step in the process.
+  </Step>
+</Steps>
+
+### Icons
+
+```mdx
+<Col rows={2}>
+  <Icon icon="Code" />
+  <Icon icon="FileText" />
+  <Icon icon="CheckCircle" />
+</Col>
+```
+
+<Row cols={3}>
+<Icon icon="Code" />
+<Icon icon="FileText" />
+<Icon icon="CheckCircle" />
+</Row>

package/docs/getting-started/automation.mdx

@@ -0,0 +1,76 @@
+---
+title: 'CLI and MCP automation'
+description: 'Build, inspect, capture, and iterate on Dory documentation from a CLI or MCP client.'
+---
+
+# CLI and MCP automation
+
+Dory can expose a local documentation project to an MCP client. The client can inspect `dory.json`, read and write MDX pages, validate compilation, build the site, and capture screenshots of the result.
+
+## Connect an MCP client
+
+From the directory containing `dory.json`, run:
+
+```bash
+dory mcp config
+```
+
+Add the printed `mcpServers.dory` entry to your MCP client's configuration. It pins the current project with `DORY_PROJECT_ROOT`, so the client does not need to launch from that directory. To start it directly:
+
+```bash
+dory mcp serve --project /path/to/docs-project
+```
+
+The server uses stdio. Its stdout carries MCP messages; build logs are returned inside tool results.
+
+## Connect to hosted documentation
+
+A Dory site served with `dory preview` also exposes a public, read-only Streamable HTTP MCP endpoint at `/mcp` (or `/docs/mcp` when `basePath` is `/docs`). It provides `site_guide`, `list_pages`, `search_docs`, and `read_page`. These tools read only files in the built `dist/` directory. The local stdio MCP server above remains the way to write pages, build, and take screenshots.
+
+Add the endpoint once in your MCP client:
+
+```bash
+codex mcp add whodb-docs --url https://docs.whodb.com/mcp
+claude mcp add --transport http whodb-docs https://docs.whodb.com/mcp
+```
+
+Replace the example URL with your Dory site. If the docs run behind a reverse proxy, forward `/mcp` to the Dory preview server. Its `dory.json` `url` must match the public hostname; for an additional preview hostname, set `DORY_MCP_ALLOWED_HOSTS` to a comma-separated list. The endpoint rejects other hostnames and cross-origin browser requests.
+
+You can also give a browsing agent just the documentation URL. Dory advertises `llms.txt` in its HTML, with links to the published `.mdx` pages and `llms-full.txt`. MCP clients still need the one-time connector command above before they can call MCP tools.
+
+## Build and review loop
+
+Ask the MCP client to call `dory_guide` first. A typical loop is:
+
+1. `dory_project` reads the site configuration and page list.
+2. `dory_reference` provides Dory's packaged component and configuration guides.
+3. `dory_read_page` and `dory_write_page` update the relevant MDX.
+4. `dory_verify_page` checks MDX compilation.
+5. `dory_check` catches broken navigation and links, then `dory_build` generates the site.
+6. `dory_screenshot` captures a route in light and dark themes; review the images and repeat as needed.
+
+The same operations are available from the CLI:
+
+```bash
+dory inspect
+dory reference components/cards.mdx
+dory check
+dory verify:content --file getting-started/quick-start.mdx
+dory build
+dory screenshot --route /getting-started/quick-start --theme light
+dory screenshot --route /getting-started/quick-start --theme dark --width 390 --height 844
+```
+
+Screenshot capture uses Chrome or Chromium. Set `DORY_CHROME_PATH` if the browser is outside the standard installation paths. Screenshots are written as PNG files under `.dory/screenshots/`; `--output` must stay in that directory.
+
+## Discover published MDX from one URL
+
+Dory sites advertise their `llms.txt` index in the page HTML. The index links to every navigation page's published `.mdx` source and to `llms-full.txt` for combined text. Give a hosted site URL to the CLI or MCP client:
+
+```bash
+dory discover https://docs.example.com
+```
+
+The `dory_discover_site` MCP tool returns the index and MDX URLs. `dory_read_remote_page` retrieves an individual published MDX page. For sites hosted under a path such as `/docs`, the HTML discovery link points to the correct index automatically. Remote discovery accepts public HTTP or HTTPS sites; local and private network addresses are blocked.
+
+The server only edits local project pages. Hosted URL discovery reads published source; it does not change the remote site.

package/docs/getting-started/configuration.mdx

@@ -0,0 +1,95 @@
+---
+title: 'Configuration'
+description: 'Configure your Dory site with dory.json — branding, navigation, fonts, colors, and more.'
+---
+
+# Configuration
+
+All Dory configuration lives in a single `dory.json` file at the project root. Pages can live in `docs/`. Here is an example:
+
+```json
+{
+  "name": "My Docs",
+  "title": "My Docs — Developer Reference",
+  "description": "The official documentation for My Project.",
+  "url": "https://docs.myproject.com",
+  "image": "/og-card.png",
+  "twitter": "@myhandle",
+  "favicon": "./favicon.svg",
+  "colors": {
+    "primary": "#6366f1",
+    "light": "#818cf8",
+    "dark": "#4f46e5"
+  },
+  "fonts": {
+    "family": "Inter",
+    "source": "https://fonts.gstatic.com/...",
+    "format": "woff2"
+  },
+  "logo": {
+    "light": "./logo/logo.svg",
+    "dark": "./logo/logo-dark.svg"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": ["introduction", "installation"]
+          }
+        ]
+      },
+      {
+        "tab": "API Reference",
+        "groups": [
+          {
+            "group": "Endpoints",
+            "pages": ["api/create", "api/update", "api/delete"]
+          }
+        ]
+      }
+    ]
+  },
+  "analytics": {
+    "posthog": {
+      "token": "phc_your_token",
+      "apiHost": "https://us.i.posthog.com"
+    }
+  }
+}
+```
+
+## Top-Level Fields
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | Yes | Site name shown in the header and browser tab. |
+| `title` | No | Custom page title. Defaults to `name`. |
+| `description` | No | Short description used for SEO. |
+| `url` | No | Your site's URL, used for social sharing previews. |
+| `image` | No | Preview image shown when sharing links on social media. |
+| `twitter` | No | Your Twitter/X handle for social meta tags. |
+| `favicon` | Yes | Path to your favicon file (SVG or PNG). |
+| `colors` | No | Brand colors. See [Theming](/configuration/theming). |
+| `fonts` | No | Custom font. See [Fonts](/configuration/fonts). |
+| `logo` | Yes | Logo paths for light and dark mode. |
+| `navigation` | Yes | Navigation structure. See [Navigation](/configuration/navigation). |
+| `analytics` | No | Analytics integrations. See [Analytics](/configuration/analytics). |
+| `i18n` | No | Translated content. See [Languages and versions](/configuration/internationalization). |
+| `versions` | No | Versioned content. See [Languages and versions](/configuration/internationalization). |
+| `embed` | No | Embeddable widget config. See [Embed](/configuration/embed). |
+
+## Configuration Sections
+
+<CardGroup cols={2}>
+  <Card title="Navigation" href="/configuration/navigation" icon="map" description="Configure tabs, groups, and pages in the sidebar." />
+  <Card title="Theming" href="/configuration/theming" icon="palette" description="Set primary, light, and dark brand colors." />
+  <Card title="Fonts" href="/configuration/fonts" icon="type" description="Use a custom web font from Google Fonts or any CDN." />
+  <Card title="Analytics" href="/configuration/analytics" icon="bar-chart" description="Integrate PostHog for page view tracking." />
+  <Card title="Documentation chat" href="/configuration/chat" icon="message-square" description="Configure a server-side model for cited answers." />
+  <Card title="Languages and versions" href="/configuration/internationalization" icon="globe" description="Organize localized and versioned pages." />
+  <Card title="Embed" href="/configuration/embed" icon="code-2" description="Configure the embeddable widget for external sites." />
+  <Card title="Full Reference" href="/configuration/dory-json" icon="file-text" description="Complete dory.json reference with all fields." />
+</CardGroup>

package/docs/getting-started/installation.mdx

@@ -0,0 +1,88 @@
+---
+title: 'Installation'
+description: 'Install Dory and start building your documentation site.'
+---
+
+# Installation
+
+## Install the CLI
+
+Install Dory globally to use the `dory` command anywhere:
+
+<CodeGroup>
+  ```bash npm
+  npm install -g @clidey/dory
+  ```
+  ```bash pnpm
+  pnpm add -g @clidey/dory
+  ```
+  ```bash yarn
+  yarn global add @clidey/dory
+  ```
+</CodeGroup>
+
+Verify the installation:
+
+```bash
+dory version
+# Prints the installed Dory version
+```
+
+## CLI Commands
+
+<AccordionGroup>
+  <Accordion title="dory init" icon="plus">
+    Creates a starter `dory.json` and `docs/introduction.mdx` in the current directory.
+  </Accordion>
+  <Accordion title="dory dev" icon="play">
+    Starts a live preview and reloads when your documentation changes.
+  </Accordion>
+  <Accordion title="dory check" icon="check">
+    Validates navigation, links, assets, anchors, and page metadata across the site.
+  </Accordion>
+  <Accordion title="dory build" icon="hammer">
+    Compiles your MDX files and outputs a static site to the `dist/` directory.
+
+    ```bash
+    dory build
+    ```
+
+    This reads your `dory.json`, processes all your pages, and produces a fully static site ready to deploy.
+  </Accordion>
+  <Accordion title="dory preview" icon="eye">
+    Serves a previously built site locally so you can review it before deploying.
+
+    ```bash
+    dory preview
+    # Serving dist/ at http://localhost:3000
+    ```
+
+    <Warning>
+      Run `dory build` before `dory preview`. The preview command serves the built output, not the source files.
+    </Warning>
+  </Accordion>
+  <Accordion title="dory version" icon="info">
+    Prints the installed version of Dory.
+
+    ```bash
+    dory version
+    # Prints the installed Dory version
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Project Structure
+
+A Dory project has this structure:
+
+```
+my-docs/
+├── dory.json          # Site configuration (required)
+└── docs/
+    ├── logo.svg        # Starter logo
+    └── introduction.mdx # Your first page
+```
+
+<Note>
+  Run Dory commands from the folder containing `dory.json`. Put MDX pages and assets in `docs/`. Existing flat projects with pages beside `dory.json` still work.
+</Note>