# Configuration

Reference Dahlia theme configuration fields, defaults, and related docs.

This reference lists top-level Dahlia theme fields. Use the linked configuration
pages for examples and behavior details.

## Config Files

Dahlia automatically reads `theme.config.json` from the Astro project root. Use
JSON when your theme configuration is plain data and you want editor completion
from the schema.

```json title="theme.config.json"
{
  "$schema": "https://astro-theme-dahlia.prosefly.dev/schema.json",
  "name": "My Docs",
  "description": "Documentation for my project.",
  "appearance": {
    "accent": "emerald"
  }
}
```

Register Dahlia without arguments when all configuration lives in JSON:

```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import dahlia from '@prosefly/astro-theme-dahlia';

export default defineConfig({
  integrations: [dahlia()],
});
```

Values passed to `dahlia({...})` override `theme.config.json`. Object options
such as `appearance`, `footer`, `iconify`, `locales`, `markdown`, `source`, and
`ui` are shallow-merged; arrays such as `siteNav`, `socials`, and `docsNav`
replace the JSON value when provided.

Component overrides are integration-only. Configure `components` in
`astro.config.ts`, not in `theme.config.json`.

## Options

| Field | Default | See |
| --- | --- | --- |
| `name` | `'Documentation'` | [Project](/docs/configuration/project/) |
| `description` | `'Project documentation.'` | [Project](/docs/configuration/project/) |
| `logo` | built-in Dahlia mark | [Project](/docs/configuration/project/) |
| `favicon` | none | [Project](/docs/configuration/project/) |
| `appearance` | `accent: 'indigo'`, `gray: 'neutral'`, `defaultMode: 'system'`, `radius: 'medium'` | [Appearance](/docs/configuration/appearance/) |
| `docsBase` | `'/'` | [Content Routing](/docs/configuration/content-routing/) |
| `defaultLocale` | first configured locale | [Internationalization](/docs/configuration/i18n/) |
| `locales` | none | [Internationalization](/docs/configuration/i18n/) |
| `ui` | built-in English messages | [Internationalization](/docs/configuration/i18n/#ui-translations) |
| `siteNav` | one Docs link | [Navbar](/docs/configuration/navbar/) |
| `socials` | `[]` | [Navbar](/docs/configuration/navbar/#social-links) |
| `docsNav` | `[]` | [Docs Navigation](/docs/configuration/docs-nav/) |
| `footer` | empty copyright and sections | [Footer](/docs/configuration/footer/) |
| `search` | `{ provider: 'local' }` | [Search](/docs/configuration/search/) |
| `assistant` | `false` | [Assistant](/docs/configuration/assistant/) |
| `llms` | `true` | [Content Routing](/docs/configuration/content-routing/#llms-files) |
| `pageActions` | copy, Markdown, ChatGPT, Claude | [Page Actions](/docs/configuration/page-actions/) |
| `source` | inferred when possible | [Source](/docs/configuration/source/) |
| `editLink` | hidden | [Source](/docs/configuration/source/#edit-links) |
| `contributors` | `false` | [Source](/docs/configuration/source/#contributors) |
| `components` | `{}` in `dahlia({...})` only | [Overriding Components](/docs/customization/overriding-components/) |
| `credits` | `true` | [Footer](/docs/configuration/footer/#credits) |
| `iconify` | default Iconify API, scan enabled | [Integrations](/docs/configuration/integrations/#iconify) |
| `markdown` | all transforms enabled, Expressive Code defaults | [Integrations](/docs/configuration/integrations/) |

## TypeScript Options

Use `defineDahliaConfig()` inside `astro.config.ts` when configuration needs
TypeScript, imports, or computed values:

```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import dahlia, { defineDahliaConfig } from '@prosefly/astro-theme-dahlia';

const dahliaConfig = defineDahliaConfig({
  name: 'My Docs',
  description: 'Documentation for my project.',
});

export default defineConfig({
  integrations: [dahlia(dahliaConfig)],
});
```

Values passed to `dahlia({...})` override `theme.config.json`.