Posts

Markdown was supposed to be the simple bit

A short note on .md, .mdx, and the irony of discovering that even simple document formats have edges.

2 min read
  • writing
  • markdown
  • tools

I thought I had found the boring bit.

Markdown felt like the answer. Plain text. Portable. Readable in any editor. Friendly to humans, machines, and version control.

That matters. A lot of knowledge work quietly dies inside tools that are good at capture and bad at escape. The document gets trapped in the app. The app becomes the workflow. The workflow becomes the work.

Markdown has a different feel. It is humble enough to disappear. A heading is a heading. A list is a list. A link is a link.

That is why Markdown is becoming something close to a universal document format for the AI era. Not because it is glamorous. Because it is legible.

Then MDX appeared

Just as I was getting smug about having kept the blog simple, I discovered that the sample post was not a .md file at all. It was .mdx.

Of course it was.

MDX is what happens when Markdown wants to become programmable. You write prose, then drop in components, charts, interactive examples, custom layouts, or little pieces of application logic.

That is genuinely useful. It is also exactly the kind of useful that makes simple systems slowly stop being simple.

With .md, I can open a file and think: this is writing.

With .mdx, I have to ask: is this writing, or is this code wearing a paragraph hat?

The irony

The irony is not that MDX is bad. It is that even the escape hatch has an escape hatch.

I went looking for the simplest possible publishing workflow:

write -> preview -> publish

Then immediately found the next layer of complexity hiding behind the file extension.

Nothing is ever quite as simple as it first looks. But that does not mean every useful complication deserves to become the default.

My current rule

For this blog, the default is boring:

.md first
.mdx only when the post genuinely needs to behave like software

Most writing does not need to behave like software.

It needs to survive being moved between tools. It needs to be easy to edit, quote, archive, and republish without dragging the whole website around with it.

So .md wins for now. MDX can wait until the writing earns the extra machinery.