# Installation

Install Astro Components in a standalone Astro site or documentation theme.

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

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

```sh
npm install @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.

```ts title="astro.config.ts"
import mdx from '@astrojs/mdx';
import { defineConfig } from 'astro/config';

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

```mdx title="src/content/docs/en/getting-started.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

<Steps>

1. **Register the shared integration.**

   ```ts title="astro.config.ts"
   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, Mermaid diagrams, or galleries.**

   ```ts title="astro.config.ts"
   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.

</Steps>

<Callout type="tip" title="Using Dahlia or Lotus">
  [`@prosefly/astro-theme-dahlia`](https://astro-theme-dahlia.prosefly.dev/) and
  [`@prosefly/astro-theme-lotus`](https://astro-theme-lotus.prosefly.dev/)
  already wire the shared integration, MDX, Iconify preloading, and their docs
  shell. Install this package directly only when you use the components outside
  those themes.
</Callout>

For detailed setup, see [Callout](/docs/astro-components/components/callout/),
[Package Manager Tabs](/docs/astro-components/package-manager-tabs/), [Mermaid Diagrams](/docs/astro-components/mermaid/),
and [Images](/docs/astro-components/images/).

## Configure Expressive Code

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

```sh
npm install astro-expressive-code
```

```ts title="astro.config.ts"
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](/docs/astro-components/expressive-code/) for `apiBase`, plugin behavior, and
how to combine this setup with `proseflyComponents()`.

## Import Paths

Use the main entry for components:

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

Use the integration entry for shared Astro setup:

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

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

```ts
import {
  remarkImageGallery,
  remarkCalloutDirectives,
  rehypeMermaid,
  unified,
} from '@prosefly/astro-components/markdown';
import { expressiveCodeHeaderIcons } from '@prosefly/astro-components/expressive-code';
```

`remarkImageGallery` is an MDX-only transform. It generates the public
`ImageGallery` component for image-only paragraphs; regular `.md` files are
not transformed. `rehypeMermaid` renders `mermaid` code blocks as SVG and must
run with `mermaid` excluded from Astro syntax highlighting.

## Component Exports

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