Markdown: Simple By Design, Limited By Default
Writing has been a static, text-on-paper exercise for most of human history — until the web. With the web, writing became interactive, dynamic, and increasingly intertwined with the software that renders it. The neat separation between "writing" and "development" has eroded to the point where one rarely makes sense without the other. For those of us who work across both, that overlap isn't a problem to solve; it’s an opportunity to embrace.
Most web writing today starts with Markdown. Created in 2003 by John Gruber, Markdown was designed as an easy-to-read, easy-to-write plain text format that could convert into HTML when needed. It’s remarkably clean for a markup language, which is why it has found its way into GitHub, Discord, Trello, and countless CMS-driven blogs. The syntax feels less invasive than HTML:
## Post Title
This is an example block of text written in HTML. We can link things up like this or format the code with **bolding** and *italics*. We can also make lists of items:
- Like this item
- Or this one
- Perhaos a third?
Compare that with the HTML equivalent, which is arguably more verbose but functionally similar:
<h2>Post Title</h2>
<p>This is an example block of text written in HTML. We can link things up like this, or format the code with <strong>bolding</strong> and <em>italics</em>. We can also make lists of items:</p>
<ul>
<li>Like this item<li>
<li>Or this one</li>
<li>Perhaos a third?</li>
</ul>
<img src="image.avif" alt="And who doesn't enjoy an image every now and then?">
As a blogging standard, Markdown is fine — if you’re writing words and maybe dropping in an image. But for articles that want to go beyond that? Markdown shows its limits. Gruber’s goal was a format for writing on the web circa 20+ years ago. The web has moved on significantly since then. What felt revolutionary then now feels a little too constrained for the kind of multimedia, interactive content writers and designers are expected to produce. Markdown didn’t anticipate — and wasn’t designed to handle — components, dynamic interfaces, and responsive interplay between text and data.
The natural evolution, as you might guess, isn’t a replacement for Markdown. It’s an extension: MDX.
Components Fill In Where Markdown Stops
Modern web development has replaced static pages with a rich ecosystem of component architectures. React, Vue, Svelte, Astro, and web components all share a common promise: reusable, responsive UI blocks that can interact. Where Markdown describes what things look like, components describe behavior and interactivity. And we can borrow their expressive power without abandoning the comfort of Markdown.
Currently, the distinction comes at a clear cost. Standard Markdown is machine-readable but static — great for prose, poor for experiences. Web frameworks, on the other hand, require so much abstraction that writing loses its flow.
MDX effectively acts as a bridge: it’s Markdown with inlined component syntax. This doesn’t mean you trade one language entirely for another — it just widens the possibilities. Writers who know Markdown can jump into MDX without learning a full templating system, yet they gain the capacity to include interactive code, graphs, forms, or any custom component directly in a text-based article.
That seems closer to the vision of a complete digital format. Markdown strips away barriers between author and publisher; MDX strips away the barrier between author and interactive web.
It's important to see this not as some abstract theory. Working on a personal article project structured around MDX has convinced me — it blends readability for authoring with functional richness in the rendered output. When you can tell a story with text, embed data-driven figures, and include interactivity that reacts instantly, the result is inherently better than a wall of text.
This is what sharing content for the web should become: the strength of the written word backed by modern web’s sensible, component-based innovations. Instead of abstracting out complexity entirely, we can selectively lean on it where it adds genuine depth. MDX puts that approach in a clean workflow, turning multimedia writing from exception —}}} Let's get that output settled.contradiction to practice. Whatever you'd call it — richer editorial, technical blogging, or ongoing documentation — blending straightforward writing with deeper interactivity may, in fact, be the genuinely web-native approach.
Building a Fluid Writing and Component Workflow
The author’s own experience with MDX took shape in a side project: teeline.online. Before becoming a software engineer, they were a journalist trained in Teeline shorthand — a system that strips out superfluous letters (a process they call “disemvowelment”) and uses a dedicated alphabet for the remaining content, enabling rapid note-taking. Finding online learning resources lacking during their studies, they began building the kind of site they wished had existed as a student.
The site is built with Svelte for its components. Its centerpiece is a dataset of shorthand characters and combinations from which hundreds of outlines can be rendered, combined, and animated as SVG paths. A modest syllabus section covers Teeline theory and best practices. Early on, the site threatened to become overrun with bespoke images and SVGs — every word had its own custom outline, and every image was created from scratch. Over time, the SVG outlines were abstracted into a core dataset capable of generating an infinite number of outlines.
Blending Content and Components
Svelte’s framework has its own variant of MDX called MDsveX. While the syntax is tightly coupled to Svelte components rather than those from other frameworks like React, the underlying principles are the same. This allowed the author to weave reusable interactive elements into the syllabus.
The first application was animated outlines in an “Alphabet” section, with individual outline cards dropped in to illustrate specific points.
Teeline’s disemvowelment script was wired into a single reusable component:
Natural for component-based work, these could be combined to show the Teeline evolution converting longhand words into shorthand outlines.
The Markdown itself remains remarkably simple:
The files sit in a tidy directory of their own:
With a bit of metadata sprinkled in, routing can render an entire section of the site. The setup feels like a fluid medium between worlds — writers can use words and pictures freely, and if a component would express an idea better, it can be built and dropped in on the fly.
A component like “WordToOutline” might not mean much to Teeline newcomers initially, but the clear connection between the Markdown and the rendered pages makes its purpose easy to infer. For growing component libraries, services like Storybook can provide organization.
The raw form of multimedia content is often unsightly — something content management systems tend to keep at arm’s length. With MDX and its ilk, the content feels friendly and legible.
Two Key Benefits
Editorial Benefits
MDX does not distract the writing and editorial flow. Traditional code languages, even HTML, are convoluted with opening and closing tags. Embedding components in content adds even more complexity. Markdown, by contrast, is far less verbose — content is a first-class citizen that takes up minimal space, remaining clear and legible. Components can be dropped in when needed without disrupting that editorial experience.
The second major benefit is reusability. Displaying the same information as raster images would require bespoke visuals for each instance — and maintaining content in images is inefficient, requiring edits in a completely different application. If the site’s design changed, dozens of images would need to be recreated in the new style. With MDX or MDsveX, a single change updates everywhere. Having built reusable components once, they can be woven throughout the syllabus knowing updates roll out across the board without affecting the editorial experience.
Creating the same content as images or videos would take considerable time. Over time, fixed assets become a form of technical — or editorial — debt that accumulates. A component-based multimedia approach proves faster and more flexible.
Tech Benefits
Reusable components in MDX allow Markdown content to become more robust without compromising legibility during authoring. MDsveX combines the clean, readable conventions of Markdown with the rich, interactive potential of Svelte components.
Knowing When MDX Is Wrong
MDX has its limitations, and they tend to surface when it is not the best choice for a project. There is a sweet spot: when you need to sprinkle additional web functionality into content, you get the best of both worlds — minimal markup and modern web features. But if components are not needed, MDX is overkill for content that simply needs to port cleanly into HTML.
Without components, MDX is akin to caring for a skinned elbow with a cast; it’s way more than what’s needed in that situation, and the returns you get from Markdown’s legibility will diminish.
If technical needs go beyond components, a more complex architecture may be required than MDX can support — you would be better served by leaning into what works best for content in your particular framework or stack.
Code does not age as well as words or images. An MDX approach brings the maintenance work of dependency updates, refactoring, and, eventually, framework migrations. The author has not yet faced migrations but finds the first two obligations well worth it — they are good habits to keep.
What Writing With MDX Changes
Writing with MDX has improved the author’s quality of writing by encouraging more lateral thinking about how to convey ideas:
Is what I’m saying best conveyed in words, an image, or a data visualization? Perhaps an interactive game?
There is far more potential to enhance words with componentry than Markdown alone offers, opening more avenues for both what content is written and how it is expressed. Those components do not come for free — MDX requires building them, regardless of whether your framework includes predefined ones. Still, the opportunities MDX opens up for writing greatly outweigh having to build or maintain a few components.
Had MDX existed in Leonardo da Vinci’s age, he might have reached for it in his journals. The complexity of his technical writing — dense with descriptions and illustrations — would have benefited from interactive demos and a better writing experience. Nor is that leap of assumption entirely gratuitous: the technical complexity of his notebooks is precisely the kind of content MDX handles well.
Further Reading
- “The Power of Pen and Paper Sketching” by Tracy Osborne
- “What Leonardo Da Vinci Can Teach Us About Web Design” by Frederick O’Brien
Enriched Writing, Not Just Markup
MDX is, in many respects, an extension of what Markdown and web writing already encourage. Content is not only words but also links, images, and semantic structure. MDX and its equivalents take the lid off the cookie jar, allowing writers to enhance their work with interactive, bespoke elements.
The question Wouldn’t it be nice if…? is rarely rhetorical on the web. There may be technical hurdles — or, as the author admits, skill and knowledge hurdles — but the range of ways thoughts can manifest on screen is part of its appeal. At the same time, plain Markdown remains perfectly viable; if components are not needed, being able to write in vanilla Markdown without trading up to MDX is entirely possible.
Just having the possibility of bespoke multimedia content is enough to change the creative process. It leaves you using words because you want to, not because you have to.
Why describe the solar system when you could render an explorable one? Why include a static image of a proposed skyscraper when a 3D model communicates more fully? Writing with MDX — or, more accurately, MDsveX — shifts the creative process and expands what answers to How do I best get this across? can include.
Codifying Creativity
Good things happen when worlds collide. Content management systems that shield writers from code are, in the author’s view, like shielding painters from wider color palettes, chefs from exotic ingredients, or sculptors from different tools. Leaning into the overlap between writing and coding gets closer to one of the web’s great joys: if you can imagine it, you can probably build it.
(gg, yk)
