# Overview Choose the right component for each documentation problem. import { Callout, Card, CardGrid, Steps } from '@prosefly/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 Use `Callout` for notes, tips, warnings, and destructive guidance that should stand apart from the surrounding prose. Use `Tabs` for package managers, frameworks, languages, or other parallel examples where the reader should pick one. Use `Accordions` for optional explanations, FAQs, and background details that should not interrupt the main path. Use `FileTree` when a reader needs to create, find, or understand files and directories. Use `Card` and `CardGrid` for related guides, feature summaries, and next-step links. Use `Steps` for installation, migration, and configuration procedures. Use package-manager tabs when readers should choose between `pnpm`, `npm`, `yarn`, and `bun`. Use Mermaid code blocks for flows, sequences, states, classes, data models, and XY charts that should build into static SVG. Use image transforms when authors should write plain Markdown screenshots and get polished figures. Use VideoPlayer for visibility-aware short clips and native controls for longer videos, with optional automatic MDX figure conversion. Add file icons and language labels to Expressive Code frames with the independent plugin. 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](https://prosefly.com/) 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 1. **Start with plain Markdown.** Write the explanation first. Add components only where the reader needs a stronger structure than headings, paragraphs, and lists. 2. **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'; ``` 3. **Use transforms for repeated patterns.** In standalone Astro projects, enable the package-manager tab or image transform that matches the content. Dahlia and [Lotus](https://astro-theme-lotus.prosefly.dev/) enable both automatically. 4. **Theme once in the shell.** Configure `--pf-*` custom properties in the site layout, not in each MDX page. Users of [Dahlia](https://astro-theme-dahlia.prosefly.dev/) or [Lotus](https://astro-theme-lotus.prosefly.dev/) usually start at step 2 because their themes already configure the Markdown transforms, Iconify preload middleware, and shared styles.