Integrations

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.

Astro Components

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

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:

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(),
  ],
});

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:

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.

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:

proseflyComponents({
  markdown: {
    packageManagerTabs: false,
  },
})

Callout Directives

The Astro Components integration supports Starlight-style admonition syntax for note, tip, warning, caution, and danger. See Admonitions for authoring examples.

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.

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 for authoring details.

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 for supported diagram types, syntax examples, rendering behavior, accessibility, styling, and troubleshooting.

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 for the complete override surface and examples.