Dahlia
Type to search documentation.

Configure

Integrations

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

View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in GrokOpen in Perplexity

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

Use the default shared integration, or register it explicitly to customize icons and content transforms.

Iconify

Preload icons used by components and project content.

Expressive Code

Render syntax-highlighted code blocks with frames, copy buttons, markers, and theme-aware styling.

Package Manager Tabs

Turn recognized npm and Python install commands into synchronized tabbed command blocks.

Callout Directives

Write admonitions with Markdown directive syntax such as :::tip.

CJK-Friendly Markdown

Make emphasis and GFM strikethrough work better in Chinese, Japanese, and Korean text.

Image Galleries

Transform Markdown image-only paragraphs into responsive gallery figures.

Mermaid

Render fenced Mermaid diagrams as theme-aware static SVG during the build.

Astro Components

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

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:

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

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.

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:

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.

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:

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

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.

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

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

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

Last updated Oct 14, 2026

Contributors