The Complete Guide to Dokly's MDX Components

Plain Markdown has a ceiling. It's excellent for headings, paragraphs, lists, and basic formatting, but the moment you need to highlight a warning, compare two code examples side by side, or walk a reader through a multi-step process, you hit that ceiling hard.

MDX—Markdown with JSX components—breaks through it. By letting you embed interactive components directly in your prose, MDX turns static pages into dynamic, rich documentation.

This guide walks through every component Dokly ships, with real examples of when to use each one.

How to Think About Components#

Components in your docs should earn their place. A well-written paragraph of Markdown will almost always beat a badly chosen component. The purpose of components isn't to decorate; it's to signal structure that prose alone can't convey.

A callout says "pay extra attention to this." A tab group says "these are parallel versions of the same thing." A step list says "order matters." When you use components well, readers scan your docs faster and absorb more.

Callout#

Callouts draw attention to content that readers might miss if it were in regular prose. Dokly supports eight variants:

Props:

• type - One of: info, note, warning, caution, error, danger, success, tip (default: info)
• title - Optional heading for the callout

Usage:

<Callout type="warning" title="API Key Security">
  Never commit your API key to version control. Use environment variables instead.
</Callout>

<Callout type="tip">
  You can use keyboard shortcuts to navigate faster. Press Cmd+K to open search.
</Callout>

When to use: Sparingly. A page with eight callouts has zero emphasis. Aim for one or two per page, reserved for content that genuinely needs to stand out.

When to skip: If the information is core to the content and every reader will read it, leave it in regular prose.

Steps and Step#

For sequential processes where order matters. Each step is numbered and visually distinct with a timeline connector.

Props:

• Steps - Wrapper component, no props
• Step - Requires title prop

Usage:

<Steps>
  <Step title="Create a project">
    Navigate to your dashboard and click "New Project."
  </Step>
  <Step title="Install the SDK">
    Add the Dokly SDK to your project:
    ```bash
    npm install dokly-sdk
    ```
  </Step>
  <Step title="Initialize the client">
    Add your API key to your environment variables:
    ```javascript
    import { Dokly } from 'dokly-sdk';
    const client = new Dokly(process.env.DOKLY_KEY);
    ```
  </Step>
</Steps>

When to use: Any ordered process—onboarding flows, integration guides, troubleshooting procedures.

When to skip: If order doesn't matter, use a regular list. Steps imply sequence; misusing them confuses readers.

Tabs#

Tabs are for content that has parallel versions—showing the same concept in multiple languages, different platforms, or different package managers.

Props:

• Tabs - Requires defaultValue to set the initially active tab
• TabsList - Wrapper for the tab triggers
• TabsTrigger - Requires value prop matching a TabsContent
• TabsContent - Requires value prop

Usage:

<Tabs defaultValue="npm">
  <TabsList>
    <TabsTrigger value="npm">npm</TabsTrigger>
    <TabsTrigger value="yarn">yarn</TabsTrigger>
    <TabsTrigger value="pnpm">pnpm</TabsTrigger>
  </TabsList>
  <TabsContent value="npm">
    ```bash
    npm install dokly-sdk
    ```
  </TabsContent>
  <TabsContent value="yarn">
    ```bash
    yarn add dokly-sdk
    ```
  </TabsContent>
  <TabsContent value="pnpm">
    ```bash
    pnpm add dokly-sdk
    ```
  </TabsContent>
</Tabs>

When to use: Installation instructions across package managers, code examples in multiple languages, platform-specific guidance (macOS vs Windows vs Linux).

Card and CardGroup#

Cards highlight a single concept, link, or resource in a visually distinct block. They're often used for landing pages, overview pages, or sections with multiple parallel options.

Card Props:

• title - Required, the card heading
• description - Optional subtitle text
• href - Optional link URL (makes the card clickable)
• icon - Optional React node for an icon
• children - Optional body content

CardGroup Props:

• cols - Number of columns: 1, 2, or 3 (default: 2)

Usage:

<Card title="Quick Start" href="/quickstart">
  Get up and running with Dokly in under 5 minutes.
</Card>

Cards can be arranged in a grid using CardGroup:

<CardGroup cols={2}>
  <Card title="REST API" href="/api/rest" description="Full reference for the REST endpoints." />
  <Card title="GraphQL" href="/api/graphql" description="Query our data with GraphQL." />
</CardGroup>

When to use: Landing pages, section overviews, anywhere you want to present a menu of choices visually rather than as a list of links.

Code Blocks#

Every code block in Dokly has syntax highlighting for over 100 languages, plus copy-to-clipboard buttons.

Basic code block:

```javascript
const client = new Dokly();
```

With a title:

```javascript title="index.js"
const client = new Dokly();
```

With line highlighting:

```javascript {2,4-6}
const client = new Dokly();
const result = await client.fetch('/users'); // highlighted
console.log(result);
if (result.ok) {                              // highlighted
  return result.data;                         // highlighted
}                                             // highlighted
```

API Documentation Components#

Dokly includes two powerful components for API documentation.

APIPlayground#

A full-featured API explorer that reads from your OpenAPI specification. Users can browse endpoints, fill in parameters, and make live requests.

Props: None (reads project context automatically)

Usage:

<APIPlayground />

The APIPlayground automatically:

• Lists all endpoints from your OpenAPI spec
• Groups endpoints by tags
• Generates example request bodies from schemas
• Provides cURL and JavaScript code snippets
• Shows response status, timing, and body

Endpoint#

For documenting individual API endpoints inline with your content. Creates a collapsible, interactive endpoint tester.

Props:

• method - Required: GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS
• path - Required: The endpoint path (e.g., /api/users)
• title - Optional: Brief description shown next to the path
• description - Optional: Longer description shown when expanded

Usage:

<Endpoint
  method="POST"
  path="/api/users"
  title="Create a user"
  description="Creates a new user account with the provided details."
/>

<Endpoint method="GET" path="/api/users/{id}" title="Get user by ID" />

Features:

• Collapsible UI to keep docs scannable
• Editable URL, query params, and headers
• Request body editor for POST/PUT/PATCH
• Live "Try it" execution
• Auto-generated cURL snippets
• Response viewer with status and timing

Combining Components#

The power of MDX shows when you combine components. A few patterns that work well:

The "Getting Started" Pattern#

<Steps>
  <Step title="Sign up">
    Create an account at [dokly.co](https://dokly.co).
  </Step>
  <Step title="Install the CLI">
    <Tabs defaultValue="npm">
      <TabsList>
        <TabsTrigger value="npm">npm</TabsTrigger>
        <TabsTrigger value="yarn">yarn</TabsTrigger>
      </TabsList>
      <TabsContent value="npm">
        ```bash
        npm install -g dokly-cli
        ```
      </TabsContent>
      <TabsContent value="yarn">
        ```bash
        yarn global add dokly-cli
        ```
      </TabsContent>
    </Tabs>
  </Step>
  <Step title="Deploy">
    <Callout type="tip">
      Set up your custom domain first for the cleanest deployment URL.
    </Callout>
    ```bash
    dokly deploy
    ```
  </Step>
</Steps>

The "Landing Page" Pattern#

# Welcome to the Dokly docs
 
Build beautiful documentation in minutes.
 
<CardGroup cols={2}>
  <Card title="Quickstart" href="/quickstart" description="Get your first docs site live in under 5 minutes." />
  <Card title="Components" href="/components" description="Every MDX component available in Dokly." />
  <Card title="Custom Domains" href="/domains" description="Host your docs on your own domain." />
  <Card title="API Reference" href="/api" description="The full Dokly API reference." />
</CardGroup>

Component Summary#

The Takeaway#

The right set of MDX components turns documentation from a chore into a medium. You can show, not just tell. You can organize complexity. You can guide readers through processes instead of dumping information on them.

Every component in this guide is available in Dokly today. Use them for your next docs page and you'll notice the difference—fewer "where do I find X" questions, faster ramp-up for new users, docs that feel professional rather than thrown together.

Start writing with Dokly—the free tier includes every component listed here, with unlimited pages and the visual editor that makes using them effortless.