# Integrations

Configure Astro Components, Iconify, Expressive Code, Mermaid, CJK Markdown, and shared content transforms.

import { Callout, Card, CardGrid } from '@prosefly/astro-components';

Dahlia includes MDX, Expressive Code, and the shared Astro Components
integration. It also configures CJK-friendly Markdown and the heading behavior
required by the theme.

<CardGrid>
  <Card icon="lucide:blocks" title="Astro Components" href="#astro-components">
    Use the default shared integration, or register it explicitly to customize
    icons and content transforms.
  </Card>
  <Card icon="lucide:sparkles" title="Iconify" href="#iconify">
    Preload icons used by components and project content.
  </Card>
  <Card icon="lucide:code-2" title="Expressive Code" href="#expressive-code">
    Render syntax-highlighted code blocks with frames, copy buttons, markers,
    and theme-aware styling.
  </Card>
  <Card icon="lucide:terminal" title="Package Manager Tabs" href="#package-manager-tabs">
    Turn recognized npm and Python install commands into synchronized tabbed
    command blocks.
  </Card>
  <Card icon="lucide:message-square-warning" title="Callout Directives" href="#callout-directives">
    Write admonitions with Markdown directive syntax such as `:::tip`.
  </Card>
  <Card icon="lucide:languages" title="CJK-Friendly Markdown" href="#cjk-friendly-markdown">
    Make emphasis and GFM strikethrough work better in Chinese, Japanese, and
    Korean text.
  </Card>
  <Card icon="lucide:images" title="Image Galleries" href="#image-galleries">
    Transform Markdown image-only paragraphs into responsive gallery figures.
  </Card>
  <Card icon="lucide:workflow" title="Mermaid" href="#mermaid">
    Render fenced Mermaid diagrams as theme-aware static SVG during the build.
  </Card>
</CardGrid>

## Astro Components

When the project does not register `@prosefly/astro-components/integration`,
Dahlia adds it with its default options. The minimal setup therefore remains:

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

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

To change Astro Components behavior, install the package directly and register
its integration yourself. Dahlia detects this registration and does not add or
configure a second instance:

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

export default defineConfig({
  integrations: [
    proseflyComponents({
      icons: {
        preload: ['lucide:sparkles'],
      },
      markdown: {
        mermaid: false,
      },
    }),
    dahlia(),
  ],
});
```

<Callout type="note" title="Configuration ownership">
  Options for Iconify, callout directives, package-manager tabs, image
  galleries, and Mermaid belong to `proseflyComponents()`. They are not Dahlia
  options and cannot be set in `theme.config.json`.
</Callout>

## Iconify

The default Astro Components integration scans static icon usage under `src`
and preloads the icons required by its shared components. Icons that are not
preloaded can still be resolved from the default Iconify API during rendering.

Register `proseflyComponents()` explicitly to preload dynamically selected
icons, disable source scanning, or use another Iconify-compatible endpoint:

```ts title="astro.config.ts"
proseflyComponents({
  icons: {
    apiBase: 'https://api.iconify.design',
    preload: ['lucide:sparkles'],
    scan: true,
  },
})
```

## Expressive Code

Expressive Code remains a Dahlia integration option and is enabled by default.

```ts title="astro.config.ts"
dahlia({
  markdown: {
    expressiveCode: {
      defaultProps: {
        showLineNumbers: false,
      },
    },
  },
})
```

Dahlia configures light and dark Shiki themes, line numbers, copy button
styling, and code frame styling to match the theme tokens.

Set `markdown.expressiveCode` to `false` to use Astro's built-in Shiki renderer.

## Package Manager Tabs

The Astro Components integration turns recognized install commands into tabbed
command blocks by default. Disable that transform in the explicit integration
when package-manager commands should remain normal code blocks:

```ts title="astro.config.ts"
proseflyComponents({
  markdown: {
    packageManagerTabs: false,
  },
})
```

## Callout Directives

The Astro Components integration supports Starlight-style admonition syntax
for `note`, `tip`, `warning`, `caution`, and `danger`. See
[Admonitions](/docs/essentials/admonitions/) for authoring examples.

```ts title="astro.config.ts"
proseflyComponents({
  markdown: {
    calloutDirectives: false,
  },
})
```

Set `markdown.calloutDirectives` to `false` in `proseflyComponents()` to keep
Markdown directives untouched.

## CJK-Friendly Markdown

`markdown.cjkFriendly` is owned by Dahlia. It controls CJK-friendly parsing for
emphasis and GFM strikethrough. The default is `auto`: Dahlia enables it when
`locales` contains a Chinese, Japanese, or Korean locale key or `lang` value.

```ts title="astro.config.ts"
dahlia({
  locales: {
    root: { label: 'English', directory: 'en' },
    'zh-cn': { label: '简体中文', lang: 'zh-CN', directory: 'zh-cn' },
  },
  markdown: {
    cjkFriendly: 'auto',
  },
})
```

Set it to `true` to force parser support on, or `false` to keep plain CommonMark
and GFM parsing.

## Image Galleries

The Astro Components integration transforms paragraphs containing only
Markdown images into responsive gallery figures. See
[Images](/docs/essentials/images/) for authoring details.

```ts title="astro.config.ts"
proseflyComponents({
  markdown: {
    imageGallery: false,
  },
})
```

Disable the transform when image-only paragraphs should remain normal Markdown
output.

## Mermaid

The Astro Components integration renders fenced `mermaid` blocks as static SVG
during content processing and excludes Mermaid source from syntax highlighting.

See the [Mermaid reference](/docs/references/mermaid/) for supported diagram
types, syntax examples, rendering behavior, accessibility, styling, and
troubleshooting.

```ts title="astro.config.ts"
proseflyComponents({
  markdown: {
    mermaid: false,
  },
})
```

Register the integration explicitly and disable this transform when Mermaid
source should remain a normal code block.

## Component Overrides

Use Dahlia's `components` option to replace selected theme components. See
[Overriding Components](/docs/customization/overriding-components/) for the
complete override surface and examples.
