why i prefer plain markdown over mdx
mdx is a great tool for someone else's problem. mine is that i want to still be able to open my notes in ten years.
a markdown file is text. an mdx file is a program.
that is the whole argument. everything below is detail.
an mdx file imports things. it renders components. it depends on a compiler version and on whichever component library you liked that year. open one from a few years ago and the words are still there, buried between <Callout> tags that point at nothing.
mdx also changes how you write. once dropping in a component is easy, you do it. the post becomes a small app. small apps rot.
what a notebook needs is short: headings, lists, links, code blocks, an image now and then, and frontmatter for date, tags, and description. astro’s markdown pipeline does all of it. shiki highlights the code. a zod schema checks the frontmatter so a typo fails the build instead of shipping. when markdown isn’t enough, an html block inside the file still works, and it is still text.
the test: open the file in obsidian, in webstorm, in less, and on github. does it read as intended in all four? markdown passes. mdx fails the moment there is a component in it.
if you are building documentation with live demos, use mdx. if you want to read your notes in ten years, don’t.