# Mintlify compatibility Map Mintlify MDX components to the Plandalf docs components that render the same authoring patterns in our theme. Source: /docs/components/mintlify-compatibility Last modified: 2026-06-20 Use this page when porting Mintlify-style MDX into Plandalf docs. The goal is not to copy Mintlify's brand, but to support the same authoring moves: progressive structure, attention blocks, prompt blocks, disclosure, API shape, navigation grids, and visual context. This parity map was checked against Mintlify's public component inventory on 2026-06-20. Mintlify lists Accordions, Badge, Banner, Callouts, Cards, Code groups, Color, Columns, Examples, Expandables, Fields, Frames, Icons, Mermaid, Panel, Prompt, Response fields, Steps, Tabs, Tiles, Tooltips, Tree, Update, View, and Visibility. Its create docs also treat text formatting, code formatting, lists, tables, reusable snippets, images, embeds, files, changelogs, personalization, and redirects as first-class authoring surfaces. Its API playground docs treat API playground overview pages, OpenAPI setup, AsyncAPI setup, manual MDX API pages, complex data types, SDK examples, multiple responses, page visibility, and troubleshooting as first-class API authoring surfaces. Plandalf supports those authoring jobs in the components below, plus small extensions and imported-runtime helpers such as `Snippet`, `Heading`, `ResponseField`, and `ApiEndpoint`. > **Parity rule** > If imported docs use a Mintlify component name, either render it directly, map it to a Plandalf alias, or document the closest supported replacement here before publishing the page. ## Mintlify path aliases Some Mintlify component pages use canonical slugs that differ from Plandalf's shorter docs slugs. Keep these aliases in place so copied internal links keep working after a port. | Mintlify path | Plandalf path | Handling | | --- | --- | --- | | `/docs/components/index` | `/docs/components` | Production redirect | | `/docs/components/mermaid-diagrams` | `/docs/components/mermaid` | Local alias page | | `/docs/components/responses` | `/docs/components/responses` | Mintlify-compatible page | | `/docs/create/text` | `/docs/components/text` | Local bridge page | | `/docs/create/code` | `/docs/components/code` | Local bridge page | | `/docs/create/list-table` | `/docs/components/lists-tables` | Local bridge page | | `/docs/create/image-embeds` | `/docs/components/image-embeds` | Local bridge page | | `/docs/create/files` | `/docs/components/files` | Local bridge page | | `/docs/create/reusable-snippets` | `/docs/components/reusable-snippets` | Local bridge page | | `/docs/create/changelogs` | `/docs/components/update` | Local bridge page | | `/docs/create/personalization` | `/docs/components/visibility` | Local bridge page | | `/docs/create/redirects` | `/docs/components/mintlify-compatibility#mintlify-path-aliases` | Local bridge page | ## Component families - [Structure](#structure-your-content): Tabs, Code groups, Steps, Columns, and Panel. - [Attention](#draw-attention): Callouts, Banner, Badge, Update, Frames, and Tooltips. - [Prompt](#showcase-ai-prompts): Prompt blocks with copy and Cursor actions. - [Disclosure](#show-and-hide-content): Accordions, Expandables, View, and Visibility. - [API](#document-your-api): Fields, Responses, ResponseField, and Examples. - [Navigation](#link-to-other-pages): Cards and Tiles with icon-led destinations. - [Visual context](#add-visual-context): Icons, Mermaid, Color, and Tree. - [Full reference](/docs/components/reference): Aliases, props, and compatibility notes. - [Showcase](/docs/components/showcase): Rendered component QA page. ## Structure your content ### Structure components - `Tabs` (Tabs, Tab): Supported. Use when a concept has a small set of named views, such as HTML, React, and Agent. - `Code groups` (CodeGroup, CodeGroups, CodeTabs, CodeBlocks, CodeBlockGroup): Supported. Use for language-specific examples with synced labels and Mintlify-style code titles. - `Text formatting` (Markdown prose): Supported. Use Markdown for emphasis, links, blockquotes, inline code, and anchors before adding heavier MDX components. - `Code formatting` (fenced code, CodeBlock): Supported. Use titled fences, `lines`, `wrap`, `highlight`, `focus`, `diff`, and `expandable` metadata before reaching for a manual component. - `Lists and tables` (Markdown lists, task lists, tables): Supported. Use native Markdown for compact sequences, checklists, nested lists, and reference tables before adding heavier component surfaces. - `Steps` (Steps, Step): Supported. Use for the main teaching path with numbered markers. - `Columns` (Columns, Column): Supported. Use sparingly for side-by-side explanation where cards would be too heavy. - `Panel` (Panel): Supported. Use for supplementary context that should not interrupt the main path. - `Heading` (Heading): Supported. Mintlify pages can emit explicit component headings between cards and sections; Plandalf preserves the level, anchor, and title. ## Draw attention ### Attention components - `Callouts` (Callout, Note, Info, Tip, Warning, Check, Danger): Supported. Use the semantic aliases for reader-facing notes and constraints. - `Banner` (Banner): Supported. Use for page-level announcements and high-priority docs notices. - `Badge` (Badge): Supported. Use inline for status labels, component availability, or short metadata. - `Update` (Update): Supported. Use for changelog-style callouts, release notes, dated entries, tags, and RSS metadata inside docs pages. - `Frames` (Frame): Supported. Use for screenshots, browser-style embeds, and captioned media. - `Images and embeds` (img, MediaImage, MediaScreenshot, iframe, video): Supported. Use Markdown images or `DocsImage` for simple assets, `MediaImage` for tracked screenshots, and `Frame` around inspectable embeds. - `Files` (a download, Card, Tree): Supported. Use native file links for downloads, icon cards for important artifacts, and trees for file placement. - `Tooltips` (Tooltip): Supported. Use for short inline explanations, not required instructions. - `Snippets` (Snippet): Plandalf extension. Use for short copyable values such as API keys, package names, headers, and offer IDs. - `Reusable snippets` (MDX imports): Supported. Store reusable MDX fragments outside `content/docs` and import them into docs pages with props. ## Showcase AI prompts ### Prompt components - `Prompt` (Prompt, AI, AskAI): Supported. Use `actions={["copy", "cursor"]}` when the prompt should support both clipboard and Cursor handoff. > **Port a Mintlify component page** > Convert the Mintlify-style MDX component page into Plandalf docs. - Keep the same teaching job. - Use Plandalf theme components. - Replace unsupported props with the closest documented alias. - Add a rendered example, props, and related component links. - Run `npm run docs:audit` after build. ## Show and hide content ### Disclosure components - `Accordions` (AccordionGroup, Accordion, Accordions): Supported. Use for grouped optional details. - `Expandables` (Expandable): Supported. Use for one local reveal inside the article. - `View` (View): Supported. Adjacent views become a switcher for human, JavaScript, React, or agent context. - `Visibility` (Visibility): Supported. Human-visible content renders publicly; agent-only content stays out of the rendered page. Use this for imported personalization-style authoring when the condition is audience context rather than product authentication state. ## Document your API ### API components - `Fields` (Fields, Params, ParamFields, Parameters, Properties, Attributes, RequestFields, RequestParams): Supported. Use for request fields, parameters, properties, and attributes. - `Responses` (Responses, ResponseFields, ResponseFieldGroup): Supported. Use as the Mintlify-compatible container for response objects, expandable nested fields, and schema explanations. - `ResponseField` (ResponseField, ResponseParam, ResponseProperty): Supported. Use for a single returned field, nested object row, or response property. - `RequestField` (RequestField, RequestParam, RequestParameter, RequestProperty): Supported. Use when imported API docs name request rows explicitly instead of generic parameter rows. - `Examples` (Example, Examples, RequestExample, ResponseExample): Supported. Request and response examples clone into the desktop API rail and update with the active endpoint. - `API playground pages` (ApiEndpoint, RequestExample, ResponseExample): Supported for manual MDX API pages. Use [API playground pages](/docs/components/api-playground) for endpoint metadata, multiple responses, SDK-style examples, complex data types, API playground overview structure, OpenAPI planning notes, AsyncAPI planning notes, page visibility, and troubleshooting. ````mdx title="api-example.mdx" ### Create a session ```bash title="POST /api/checkout/sessions" curl -X POST "https://api.plandalf.com/api/checkout/sessions" ``` ### Session response ```json title="201 checkout session" { "session": { "id": "cs_123", "status": "open" } } ``` ```` ## Link to other pages ### Navigation components - `Cards` (CardGroup, Card, Cards): Supported. Use for a small set of high-value next steps. Linked cards should carry icons. - `Tiles` (TileGroup, Tile, Tiles, TileGrid): Supported. Use for dense component catalogs and overview grids. Linked tiles should carry icons. ## Add visual context ### Visual components - `Icons` (Icon): Supported with Lucide-backed aliases. Missing aliases should be added to `DocsIcon.astro` instead of rendering fallback icons. - `Mermaid diagrams` (Mermaid): Supported. Use for flows, sequences, and architecture sketches that benefit from structured diagrams. - `Color` (Color, ColorItem, ColorRow, ColorPalette, ColorSwatch): Supported. Use for palette swatches and theme tokens. - `Tree` (Tree, TreeFolder, TreeFile, Folder, File): Supported. Use for file and folder structure. ## Related pages - [Components overview](/docs/components): Start with the family-level guide. - [Reference](/docs/components/reference): Check aliases and props. - [API examples](/docs/components/api-fields-examples): See endpoint-aware examples.