Overview - Astro Components

Use @prosefly/astro-components when your docs have outgrown plain Markdown but you still want authors to write normal MDX. The package focuses on common documentation jobs rather than application UI: explain risk, compare options, show structure, and guide readers through a task.

Choose By Reader Need

Warn or emphasize

Use Callout for notes, tips, warnings, and destructive guidance that should stand apart from the surrounding prose.

Show equivalent choices

Use Tabs for package managers, frameworks, languages, or other parallel examples where the reader should pick one.

Keep secondary detail nearby

Use Accordions for optional explanations, FAQs, and background details that should not interrupt the main path.

Explain project structure

Use FileTree when a reader needs to create, find, or understand files and directories.

Point readers forward

Use Card and CardGrid for related guides, feature summaries, and next-step links.

Walk through a process

Use Steps for installation, migration, and configuration procedures.

Generate install tabs

Use package-manager tabs when readers should choose between pnpm, npm, yarn, and bun.

Explain a system

Use Mermaid code blocks for flows, sequences, states, classes, data models, and XY charts that should build into static SVG.

Render image galleries

Use image transforms when authors should write plain Markdown screenshots and get polished figures.

Present video clips

Use VideoPlayer for visibility-aware short clips and native controls for longer videos, with optional automatic MDX figure conversion.

Enhance code blocks

Add file icons and language labels to Expressive Code frames with the independent plugin.

Keep pages scannable

Prefer the smallest component that solves the reader’s problem. A page with a few well-placed components is usually easier to read than a page where every paragraph is boxed or interactive.

Visual Editing With Prosefly

Prosefly natively supports Prosefly components in its visual editor. Authors can create and edit content with these components visually, alongside the Markdown and MDX authoring options described here.

Build A Page

Start with plain Markdown.

Write the explanation first. Add components only where the reader needs a stronger structure than headings, paragraphs, and lists.
Import locally.

Import components at the top of the MDX file so the page makes its own dependencies obvious.
mdx
```
import { Callout, Steps } from '@prosefly/astro-components';
```
Use transforms for repeated patterns.

In standalone Astro projects, enable the package-manager tab or image transform that matches the content. Dahlia and Lotus enable both automatically.
Theme once in the shell.

Configure --pf-* custom properties in the site layout, not in each MDX page.

Users of Dahlia or Lotus usually start at step 2 because their themes already configure the Markdown transforms, Iconify preload middleware, and shared styles.