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",
  "styles": ["./custom.css"],
  "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.

Global stylesheets#

styles is an optional array of local .css paths, resolved from the documentation content directory. Files load once, in order, after Dory's default styles. See Theming for setup and examples.

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 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 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 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.

JSON

"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "pages": ["introduction", "installation"]
        }
      ]
    }
  ]
}

See Navigation for the full structure reference.

Analytics#

JSON

"analytics": {
  "posthog": {
    "token": "phc_your_token",
    "apiHost": "https://us.i.posthog.com"
  }
}

See 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 for embedding configuration.

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.

Was this page helpful?

Full Example#

Site Identity#

Repository#

Global stylesheets#

Colors#

Fonts#

Theme#

Logo#

Navigation#

Analytics#

Embed#

Social preview images#