@clidey/dory 1.0.7 → 1.9.0

package/docs/configuration/dory-json.mdx

@@ -0,0 +1,278 @@
+---
+title: 'dory.json Reference'
+description: 'Complete reference for all fields in the dory.json configuration file.'
+---
+
+# dory.json Reference
+
+The `dory.json` file is the single configuration file for your Dory documentation site. It controls navigation, branding, analytics, and more.
+
+## Full Example
+
+```json
+{
+  "name": "My Docs",
+  "title": "My Docs — Developer Reference",
+  "description": "The official developer documentation.",
+  "url": "https://docs.example.com",
+  "image": "/og-card.png",
+  "twitter": "@yourhandle",
+  "favicon": "./favicon.svg",
+  "colors": {
+    "primary": "#6366f1",
+    "light": "#818cf8",
+    "dark": "#4f46e5",
+    "background": "#1a1a2e",
+    "surface": "#242440",
+    "surfaceElevated": "#2e2e4a",
+    "foreground": "#f5f5f7",
+    "mutedForeground": "#a0a0b0",
+    "border": "rgba(255, 255, 255, 0.1)",
+    "accent": "#60a5fa"
+  },
+  "fonts": {
+    "family": "Inter",
+    "source": "https://fonts.gstatic.com/s/inter/v19/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2",
+    "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"
+    }
+  },
+  "theme": {
+    "mode": "dark",
+    "radius": "0.5rem"
+  },
+  "logo": {
+    "light": "./logo/logo.svg",
+    "dark": "./logo/logo-dark.svg"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": ["introduction", "installation"]
+          }
+        ]
+      }
+    ]
+  },
+  "analytics": {
+    "posthog": {
+      "token": "phc_your_token",
+      "apiHost": "https://us.i.posthog.com"
+    }
+  },
+  "embed": {
+    "enabled": true,
+    "defaults": {
+      "position": "bottom-right",
+      "width": 400,
+      "height": 600,
+      "theme": "system"
+    }
+  }
+}
+```
+
+## Site Identity
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | **Yes** | Site name shown in the header and browser tab. |
+| `title` | No | Custom title override. Defaults to `name`. |
+| `description` | No | Meta description for SEO and social sharing. |
+| `url` | No | Origin the site is published at, e.g. `"https://example.com"`. Used for canonical links, the sitemap and `llms.txt`. |
+| `basePath` | No | Path prefix the site is served under, e.g. `"/docs"` when it lives at `https://example.com/docs`. Asset URLs, navigation, generated JSON and the dev/preview servers all honour it. Defaults to the root. |
+| `image` | No | Preview image shown when links are shared on social media. |
+| `twitter` | No | Your Twitter/X handle (e.g. `"@yourhandle"`). |
+| `favicon` | **Yes** | Path to favicon file. Supports SVG and PNG. |
+| `version` | No | Text in the sidebar version card, e.g. `"1.0.8 · Latest"`. |
+| `versions` | No | Other published versions as `[{ "label": "1.0.7", "url": "https://…" }]`. When set, the version card opens a picker that goes to the chosen URL. |
+| `copyright` | No | Name in the footer copyright line. Defaults to `name`. |
+
+## Repository
+
+```json
+"repository": {
+  "url": "https://github.com/clidey/dory",
+  "branch": "main",
+  "path": "docs"
+}
+```
+
+When set, the "On this page" rail shows **Edit this page** and **Report an issue** links. URLs follow the GitHub format.
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `url` | **Yes** | Repository URL. |
+| `branch` | No | Branch the edit link opens. Defaults to `main`. |
+| `path` | No | Folder holding the docs inside the repository. Defaults to the repository root. |
+
+## Colors
+
+```json
+"colors": {
+  "primary": "#6366f1",
+  "light": "#818cf8",
+  "dark": "#4f46e5"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `primary` | Main brand color. Used for links, active states, and accents. |
+| `light` | Lighter variant used in light mode. |
+| `dark` | Darker variant used in dark mode. |
+
+See [Theming](/configuration/theming) for more detail.
+
+## Fonts
+
+```json
+"fonts": {
+  "family": "Inter",
+  "source": "https://fonts.gstatic.com/...",
+  "format": "woff2"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `family` | The font name (e.g. `"Inter"`, `"Montserrat"`). |
+| `source` | Direct URL to the font file. |
+| `format` | Font format — use `"woff2"` for best compatibility. |
+
+See [Fonts](/configuration/fonts) for more detail.
+
+## Theme
+
+```json
+"theme": {
+  "mode": "dark",
+  "radius": "0.5rem"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `mode` | `"dark"`, `"light"`, or `"system"` (default). Forces the site into a specific color scheme. |
+| `radius` | Base border-radius for UI elements. |
+
+See [Theming](/configuration/theming) for full theming documentation.
+
+## Logo
+
+```json
+"logo": {
+  "light": "./logo/logo.svg",
+  "dark": "./logo/logo-dark.svg"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `light` | Path to logo for light mode. |
+| `dark` | Path to logo for dark mode. Can be the same as `light` if your logo works on both backgrounds. |
+
+## Navigation
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "Documentation",
+      "groups": [
+        {
+          "group": "Getting Started",
+          "pages": ["introduction", "installation"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+See [Navigation](/configuration/navigation) for the full structure reference.
+
+## Analytics
+
+```json
+"analytics": {
+  "posthog": {
+    "token": "phc_your_token",
+    "apiHost": "https://us.i.posthog.com"
+  }
+}
+```
+
+See [Analytics](/configuration/analytics) for setup instructions.
+
+## Embed
+
+```json
+"embed": {
+  "enabled": true,
+  "defaults": {
+    "position": "bottom-right",
+    "width": 400,
+    "height": 600,
+    "theme": "system",
+    "showOverlay": true,
+    "closeOnEscape": true,
+    "closeOnOverlayClick": true
+  },
+  "branding": {
+    "showLogo": true,
+    "showName": true
+  },
+  "features": {
+    "search": true,
+    "toc": true,
+    "codeBlocks": true,
+    "mermaid": true,
+    "katex": true,
+    "apiPlayground": true,
+    "darkMode": true
+  }
+}
+```
+
+See [Embed](/configuration/embed) for embedding configuration.
+
+## Social preview images
+
+Dory automatically generates a 1200 × 630 PNG for every documentation page during `dory build`. Each image includes your site name, local logo, brand colors, page title, and description. Open Graph and Twitter metadata point to the page's image. Set `url` so these links are absolute.
+
+Override an individual page's image in its frontmatter:
+
+```yaml
+---
+title: Installation
+description: Install and configure the application.
+image: /images/installation-preview.png
+---
+```
+
+To use a shared site image instead of generating page images:
+
+```json
+{
+  "image": "/social-card.png",
+  "seo": {
+    "generateSocialImages": false
+  }
+}
+```
+
+Generated files live in the build output under `_dory/social/`; they do not need to be committed. Generation uses a bundled Hanken Grotesk font and requires no browser or network connection. Local TTF or OTF heading fonts can be configured through `fonts.heading.source`. Remote logos and font URLs are not fetched during image generation.

package/docs/configuration/embed.mdx

@@ -0,0 +1,73 @@
+---
+title: Embed
+description: Open contextual Dory documentation inside another application.
+---
+
+# Embed
+
+Dory can open a hosted documentation site in a slide-out iframe. The host application chooses the starting documentation route and can navigate the iframe when its own context changes. Dory keeps its search and page navigation inside the iframe.
+
+## Allow the host origin
+
+For a host on another origin, add its exact origin to the documentation site's `dory.json` and rebuild:
+
+```json
+{
+  "embed": {
+    "security": {
+      "allowedOrigins": ["https://app.example.com"]
+    }
+  }
+}
+```
+
+Use an origin without a path or trailing slash. Dory's preview server allows framing from these origins. If you serve the static build with another web server, configure its `Content-Security-Policy` `frame-ancestors` directive for the same origins and do not send `X-Frame-Options: SAMEORIGIN` on embeddable pages. Keep the list limited to applications you control.
+
+## Add the widget
+
+Load the `embed.js` file from the hosted docs, then initialize `DoryDocs`. The script derives the docs URL from its own address, including a `/docs` base path when present.
+
+```html
+<button id="docs-help" type="button">Help</button>
+<script src="https://docs.example.com/embed.js"></script>
+<script>
+  window.DoryDocs.init({
+    trigger: '#docs-help',
+    position: 'right',
+    width: 560,
+    theme: 'inherit',
+    initialPath: '/getting-started',
+    onNavigate(path) {
+      console.log('Reader opened', path);
+    },
+  });
+</script>
+```
+
+The widget loads when the reader opens it. `theme: 'inherit'` uses the host's light or dark theme on first open. Call `setTheme` when the host theme changes.
+
+## Open the page that matches the app
+
+Map application routes or selected objects to documentation routes in the host. For example:
+
+```js
+window.DoryDocs.open('/apps/overview');
+window.DoryDocs.navigate('/apps/building-a-transform');
+window.DoryDocs.setTheme('dark');
+```
+
+`open(path)` opens the widget at a route. `navigate(path)` changes its current page. `close()`, `toggle()`, `isOpen()`, and `destroy()` manage the widget. A route change inside the iframe calls `onNavigate(path)` in the host. Messaging checks both the iframe window and the docs origin; the docs only send messages to an origin listed in `embed.security.allowedOrigins` or their own origin.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `position` | `right` | `left`, `right`, or `bottom` |
+| `width` | `500` | Width in pixels or a CSS width for side panels |
+| `height` | `100vh` | Height of a bottom panel |
+| `theme` | `inherit` | `inherit`, `light`, or `dark` |
+| `initialPath` | `/` | Route shown on first open |
+| `trigger` | — | CSS selector or element to open the widget |
+| `showOverlay` | `true` | Dim the host behind the widget |
+| `closeOnEscape` | `true` | Close when Escape is pressed |
+| `closeOnOverlayClick` | `true` | Close when the overlay is clicked |
+
+The embed displays published documentation. It does not store or edit MDX, and it does not pass host credentials into the iframe. Keep private documentation behind your own authenticated hosting layer. To create docs from an application, generate MDX and `dory.json`, run `dory build`, and publish the resulting site.

package/docs/configuration/fonts.mdx

@@ -0,0 +1,86 @@
+---
+title: 'Fonts'
+description: 'Configure a custom web font for your documentation site using Google Fonts or any CDN.'
+---
+
+# Fonts
+
+Dory uses the self-hosted Hanken Grotesk, Bricolage Grotesque, and JetBrains Mono fonts from `@clidey/ux` by default. You can set custom fonts in `dory.json` using a stylesheet URL or your own font files.
+
+## Configuration
+
+```json
+"fonts": {
+  "family": "Inter",
+  "source": "https://fonts.gstatic.com/s/inter/v19/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2",
+  "format": "woff2"
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `family` | The font name (e.g. `"Inter"`, `"Montserrat"`, `"Fira Code"`). |
+| `source` | Direct URL to the font file. See below for how to get this from Google Fonts. |
+| `format` | Font format. Use `"woff2"` for the best browser support. |
+
+## Getting a Font URL from Google Fonts
+
+<Steps>
+  <Step title="Visit Google Fonts">
+    Go to [fonts.google.com](https://fonts.google.com) and find the font you want.
+  </Step>
+  <Step title="Select a weight">
+    Click the font, then select the weight you want (e.g. Regular 400). Click **Get font** → **Get embed code**.
+  </Step>
+  <Step title="Copy the font URL">
+    In the embed panel, switch to the **CSS** tab. Find the line that starts with `src: url(` and copy the URL inside the parentheses.
+
+    For Inter, it looks like this:
+    ```
+    https://fonts.gstatic.com/s/inter/v19/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2
+    ```
+  </Step>
+  <Step title="Update dory.json">
+    Set `family` to the font name, `source` to the URL you copied, and `format` to `"woff2"`.
+  </Step>
+</Steps>
+
+## Popular Font Configurations
+
+<AccordionGroup>
+  <Accordion title="Inter" icon="type">
+    ```json
+    "fonts": {
+      "family": "Inter",
+      "source": "https://fonts.gstatic.com/s/inter/v19/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiJ-Ek-_EeA.woff2",
+      "format": "woff2"
+    }
+    ```
+  </Accordion>
+  <Accordion title="Montserrat" icon="type">
+    ```json
+    "fonts": {
+      "family": "Montserrat",
+      "source": "https://fonts.gstatic.com/s/montserrat/v29/JTUSjIg1_i6t8kCHKm459WlhyyTh89Y.woff2",
+      "format": "woff2"
+    }
+    ```
+  </Accordion>
+  <Accordion title="Geist (Vercel)" icon="type">
+    ```json
+    "fonts": {
+      "family": "Geist",
+      "source": "https://fonts.gstatic.com/s/geist/v1/gyByhwUxId8gMEwcGFWNOITD-w.woff2",
+      "format": "woff2"
+    }
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Default Font
+
+If no `fonts` configuration is provided, Dory uses the Clidey Design fonts bundled with `@clidey/ux`. They load from the built site without a Google Fonts request.
+
+<Tip>
+  For a polished look, set a custom font that matches your brand. Google Fonts has hundreds of free options and the setup takes under a minute.
+</Tip>

package/docs/configuration/internationalization.mdx

@@ -0,0 +1,61 @@
+---
+title: Languages and versions
+description: Publish translated and versioned documentation in one Dory site.
+---
+
+# Languages and versions
+
+Dory uses file paths for translated and versioned pages. Existing sites keep their current URLs. The default language and current version stay at the root.
+
+## Add a language
+
+Run `dory i18n:init fr` in your project. Dory adds the locale to `dory.json` and creates `.mdx.template` copies of your default pages under `docs/fr/`. Translate a template and rename it to `.mdx` when it is ready to publish. Re-running the command only creates missing templates; it leaves authored translations untouched.
+
+Add `i18n` to `dory.json`:
+
+```json
+{
+  "i18n": {
+    "defaultLocale": "en",
+    "locales": [
+      { "code": "en", "label": "English" },
+      { "code": "fr", "label": "Français" }
+    ]
+  }
+}
+```
+
+Keep English pages where they are. Place the French version of `docs/introduction.mdx` at `docs/fr/introduction.mdx`. It publishes at `/fr/introduction`. Dory shows a language picker when more than one locale is configured. When the matching page exists, switching languages keeps the reader on that page. Otherwise, it opens the first page in the selected language.
+
+Translate page titles and descriptions in each file's frontmatter. To translate tab and group labels, add a complete `navigation` object to that locale's entry. Use the same page keys as the default navigation, relative to the locale directory:
+
+```json
+{
+  "code": "fr",
+  "label": "Français",
+  "navigation": {
+    "tabs": [{
+      "tab": "Guides",
+      "groups": [{ "group": "Démarrage", "pages": ["introduction"] }]
+    }]
+  }
+}
+```
+
+Only publish translated pages you have written. Dory does not generate machine translations or silently show English text at a French URL. Built pages use the locale in their HTML `lang` attribute and include alternate language links for pages that exist in both languages.
+
+## Add an older version
+
+Add a version with an `id`. The current version stays at the root, and older content goes in a folder with the version ID:
+
+```json
+{
+  "version": "2.0 · Latest",
+  "versions": [{ "id": "v1", "label": "1.0" }]
+}
+```
+
+For example, `docs/v1/introduction.mdx` publishes at `/v1/introduction`. The version picker keeps the reader on the same page where it exists. You can set a version's `navigation` to describe that version's pages. Existing `versions` entries with external `url` values continue to work.
+
+For translated older versions, place files under `docs/fr/v1/`. Their URLs start with `/fr/v1/`.
+If an older translation has different pages, set `versions.v1` inside the French locale entry to a complete navigation object for that content.