Installation

Install the package where your MDX content is rendered. Dahlia and Lotus already include the shared integration; standalone Astro sites can register it directly for icon preloading, Markdown transforms, and gallery assets.

Install

pnpm add @prosefly/astro-components

npm install @prosefly/astro-components

yarn add @prosefly/astro-components

bun add @prosefly/astro-components

Use In MDX

Standalone Astro projects need MDX configured before they can render component imports inside .mdx files. If the project already renders MDX pages, or if it uses Dahlia or Lotus, skip this setup.

import mdx from '@astrojs/mdx';
import { defineConfig } from 'astro/config';

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

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

<Callout type="tip" title="Keep examples close to the task">
  Import only the components used by the current page.
</Callout>

<Steps>

1. Install the package.
2. Import the component.
3. Write normal Markdown inside the component.

</Steps>

Configure Optional Features

1. Register the shared integration.

   import { defineConfig } from 'astro/config';
   import proseflyComponents from '@prosefly/astro-components/integration';
   
   export default defineConfig({
     integrations: [
       proseflyComponents({
         icons: { preload: ['lucide:sparkles', 'simple-icons:github'] },
       }),
     ],
   });

2. Configure feature switches if you want to disable callout directives, automatic tabs, or galleries.

   import { defineConfig } from 'astro/config';
   import proseflyComponents from '@prosefly/astro-components/integration';
   
   export default defineConfig({
     integrations: [proseflyComponents({ markdown: { imageGallery: false } })],
   });

3. Set theme tokens in the layout.

   Components have fallbacks, but a site-level token set keeps them visually aligned with the surrounding docs.

For detailed setup, see Callout, Package Manager Tabs, and Images.

Configure Expressive Code

Expressive Code is an independent integration. Install astro-expressive-code, then add the Prosefly plugin to its plugins array:

pnpm add astro-expressive-code

npm install astro-expressive-code

yarn add astro-expressive-code

bun add astro-expressive-code

import { defineConfig } from 'astro/config';
import astroExpressiveCode from 'astro-expressive-code';
import { expressiveCodeHeaderIcons } from '@prosefly/astro-components/expressive-code';

export default defineConfig({
  integrations: [
    astroExpressiveCode({
      plugins: [expressiveCodeHeaderIcons()],
    }),
  ],
});

See Expressive Code for apiBase, plugin behavior, and how to combine this setup with proseflyComponents().

Import Paths

Use the main entry for components:

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

Use the integration entry for shared Astro setup:

import proseflyComponents from '@prosefly/astro-components/integration';

Use the standalone subpath entries only when configuring a feature separately:

import {
  rehypeImageGallery,
  remarkCalloutDirectives,
  unified,
} from '@prosefly/astro-components/markdown';
import { expressiveCodeHeaderIcons } from '@prosefly/astro-components/expressive-code';

Component Exports

• AccordionItem and Accordions
• Badge
• Callout
• Card and CardGrid
• FileTree
• Icon
• Steps
• TabItem and Tabs