MDX in Action: Stuffing a Pokédex into a Blog Post

One day I decided I wanted an interactive Pokédex inside a blog post.

A normal person would think: that’s impossible, Markdown is just plain text.

Then I discovered MDX.

What Is MDX

MDX = Markdown + JSX.

Simply put, you can write React components directly inside a .mdx file, like this:

# This is a normal article

Some content...

<MyComponent client:load />

More content...

The rest is handled by Astro. It renders the Markdown as HTML and hydrates the React components into interactive islands.

I wrote a Pokédex component, then called it here:

import Pokedex from '../../../components/Pokedex';

<Pokedex client:load />

Just those two lines. Then, after a tiny bit of tweaking —

Multilingual search in Chinese, English, Japanese, and Spanish. 18 type filters. Debounced queries. Pagination.

(“Tiny bit.”)

Astro runs zero client-side JS by default. To bring a React component to life, you need a hydration directive:

Directive	Timing	Best for
`client:load`	Immediately on load	Needs interaction right away (like a Pokédex)
`client:idle`	When the browser is idle	Low-priority widgets
`client:visible`	When scrolled into view	Components lower on the page
`client:only="react"`	Client-only, skips SSR	Components that need browser APIs

The Pokédex starts fetching data as soon as the page loads, so client:load it is.

Inside MDX, imports must use relative paths — path aliases won’t work:

✅ import Pokedex from '../../../components/Pokedex';
❌ import Pokedex from '@/components/Pokedex';

Astro resolves MDX at build time, and aliases may not be available at that stage. A few extra ../ never hurt anyone.

MDX in one sentence: write React inside Markdown, write Markdown inside React.

As for the PokeAPI GraphQL calls, the multilingual mappings, the debounced search… those are all part of the “tiny bit” of tweaking. Not important.

What matters is that my blog post now has a Pokédex.

That’s the only thing that truly matters.