Skip to main content

Cards, tabs, and admonitions

Docsio ships with a small set of built-in MDX components: <Card>, <CardGrid>, admonitions (:::tip, :::note, etc), and tabbed code blocks. Use them where they help, skip them otherwise. The fastest way to write bad docs is to wrap every paragraph in a different component.

When each component earns its weight

Cards and CardGrid

Best for: navigation-style sections. The "What's inside this category?" / "Pick the path that fits" / "Next step?" sections.

import {Card, CardGrid} from '@site/src/components/Card';

<CardGrid cols={2}>
  <Card title="From a URL" href="/getting-started/from-a-url" icon={<i className="ph ph-globe" />}>
    Paste your product's website. Docsio extracts the brand and writes your docs.
  </Card>
  <Card title="From your files" href="/getting-started/from-files" icon={<i className="ph ph-files" />}>
    Drag in PRDs, internal wikis, API specs.
  </Card>
</CardGrid>

Two columns is the right default. Three works if your card text is short. One-column cards (full-width) are pointless — just use a heading and a paragraph.

Admonitions

Best for: short asides where you need the reader to pause briefly.

:::tip
You can preview your changes before publishing — useful for checking the rendered look of MDX components.
:::

:::warning
Don't roll back if you've published sensitive content. Rollback restores it; you need to also rotate the leaked secret.
:::

Five variants: note, tip, info, warning, danger. Use them sparingly. A :::warning::: after every paragraph desensitizes readers.

Tabbed code blocks

Best for: same-task-multiple-languages reference pages.

```bash title="npm" tabbed
npm install @docsio/sdk
```

```bash title="pnpm" tabbed
pnpm add @docsio/sdk
```

```bash title="yarn" tabbed
yarn add @docsio/sdk
```

Don't use tabs to hide content. Anything important should be visible without clicking.

Custom MDX components

For things the built-ins don't cover — pricing tables, comparison matrices, custom layouts — write your own under src/components/. Pages can import them like any React component. See the reference for components.

A few ideas of when this is genuinely useful:

  • A pricing comparison block on the billing pages.
  • A status badge component for showing release status (<StatusBadge status="beta">).
  • An interactive expandable example — a "Show advanced options" toggle.

What we don't recommend

  • Steps as a custom component. Mintlify has <Steps>. Numbered markdown lists work just as well, render in plain markdown, and copy cleanly when AI assistants quote.
  • Accordion / collapsible sections everywhere. They hide content the reader probably needs. Use sparingly.
  • A different layout component for every page. Custom hero sections, custom feature grids, custom comparison tables — at three or four custom layouts, your docs stop feeling like a docs site.
  • Wrapping everything in <Card>. Cards are for navigation. Body content goes in regular markdown.

A simple test

Before adding a component, ask: "Could I have done this with a heading + a paragraph + a link?" If yes, do that instead. Components should add visual structure that genuinely helps the reader, not distract from the writing.