MDX basics

MDX is Markdown with React components. Everything that works in Markdown works in MDX. Plus you can drop React components — <Callout>, <Tabs>, etc. — anywhere a paragraph would go.

This page is the practical reference. For component-specific docs, see Components.

Markdown that works#

Standard Markdown:

# Heading 1
## Heading 2
### Heading 3
 
**bold** and *italic* and ~~strikethrough~~ and `inline code`.
 
> A blockquote.
 
[A link](https://dokly.co)
 
![An image](./image.png)
 
- Bullet
- Another
  - Nested
 
1. Ordered
2. List
 
| Column A | Column B |
|----------|----------|
| Cell 1   | Cell 2   |
 
---
 
(That's a horizontal rule above.)
 
```js
const x = 42;

 
Everything renders the way you'd expect.
 
## Components
 
Components look like JSX:
 
```mdx
<Callout type="tip">
  This is a tip.
</Callout>

Three rules:

1. Component names start with a capital letter. <Callout> works. <callout> doesn't.
2. Self-closing if no children. <Divider /> not <Divider>.
3. Props are written like HTML attributes, with = and quoted values: <Callout type="tip">.

For props with non-string values (numbers, arrays, objects), use curly braces:

<CardGroup cols={2}>
  ...
</CardGroup>
 
<APIPlayground
  parameters={[{ name: "id", required: true }]}
/>

Mixing Markdown and components#

You can put Markdown inside components:

<Callout type="tip">
  Use the slash menu to insert components.
 
  - It's faster than typing JSX.
  - It enforces correct prop names.
</Callout>

You can also use components inside Markdown:

| Feature | <Badge color="yellow">Pro</Badge> |
|---------|-------|
| Custom domain | Yes |

Frontmatter#

Every page starts with a YAML frontmatter block:

---
title: "Page title"
description: "A short description for SEO."
slug: section/page-slug
parent: section
order: 0
---

Frontmatter is required for new pages — it sets the page's URL, title, and where it sits in the tree. See Frontmatter for every field.

What doesn't work#

A few things from "standard MDX" that Dokly intentionally limits:

• Importing external React components. Only the built-in components (<Callout>, <Tabs>, etc.) work. You can't import { MyWidget } from "./my-widget".
• JavaScript expressions inside MDX. {2 + 2} doesn't render a 4. Curly braces are reserved for prop values only.
• HTML scripts and iframes. No <script>, no <iframe>. For embeds (YouTube, CodeSandbox), use the <Embed> component.

This is a deliberate trade — it keeps your docs portable and prevents one bad MDX file from breaking your build.

Where next#