Writing in MDX

Dokly pages are MDX. You'll rarely see the raw MDX (the editor handles it for you), but understanding the model helps you write faster.

Markdown is the base layer#

Everything Markdown supports works in Dokly:

# Heading 1
## Heading 2
### Heading 3
 
**Bold**, *italic*, `inline code`, [a link](https://dokly.co).
 
- Bullet
- Another bullet
  - Nested bullet
 
1. Ordered
2. List
 
> A blockquote.
 
---
 
A horizontal rule above this line.

The editor renders all of this with one shortcut: type the syntax, press space, and the block transforms.

Components extend it#

Where Dokly goes beyond Markdown is components. Components are React elements you can drop into your page like any other block. They give you callouts, tabs, steps, cards, and more.

A callout in raw MDX looks like this:

<Callout type="tip" title="Pro tip">
  Use the slash menu to add components instead of typing the JSX.
</Callout>

Renders as:

You almost never have to type the JSX. Use the slash menu (/callout) and the editor inserts the component for you with the right props.

The block model#

Every chunk of content in the editor is a block:

• A paragraph is a block.
• A heading is a block.
• A callout is a block.
• A code block is (a block).

Blocks have:

• A drag handle that appears on hover (left of the block).
• A **+** button to insert a new block above or below.
• Settings specific to that block type (e.g., callout type, code language).

You can move blocks by dragging the handle, delete by selecting and pressing backspace at the start of the block, and duplicate with ⌘D.

What works in MDX#

Feature Works Notes Headings (H1–H6) Yes H1 should be the page title only Bold, italic, strikethrough Yes Inline code Yes Backticks Code blocks Yes Triple backticks, language tag Links Yes Markdown or <a> Images Yes Drag, paste, or /image Lists Yes Bulleted, ordered, task lists Tables Yes Markdown pipe syntax or /table Blockquotes Yes > HTML Limited Only allowed React components Frontmatter Yes YAML at the top — see Frontmatter Math Not yet On the roadmap Mermaid Not yet On the roadmap

Switching to raw MDX#

Some people prefer typing MDX directly. Click the </> Source toggle in the toolbar to switch to a raw MDX text view. Edit there, switch back, and the visual editor catches up.

This is also useful for debugging — if a component isn't rendering the way you expect, the source view shows you exactly what the editor saved.

Next#