Mdx: Usage is vague

[scally]

This project seems interesting but I’m not able to tell what problem it’s solving. Why do I want this? Some comparison between its usage versus existing JSX usage might go a long way towards helping illustrate this.

Please take this as hopefully constructive feedback and not negativity — I would really like to know more.

[timneutkens]

From the readme:

It combines the readability of Markdown with the expressivity of JSX. The best of both worlds.

The problem it solves is that writing JSX slowed us down a lot while writing documentation/blog-posts while writing purely in markdown restricted us to only the elements markdown supports. As we tend to write hybrid blog posts on zeit.co/blog and zeit.co/docs we came up with a solution where you can write markdown which is enhanced with some javascript/jsx features.

You can read more about it here in the initial proposal: https://spectrum.chat/thread/1021be59-2738-4511-aceb-c66921050b9a

[madiodio]

I think this project is already a compelling use case: Docz.

[lazerwalker]

Hey! I just stumbled on your project, and wanted to +1 this (I actually popped into the GH Issues to open up something like this myself before I saw this issue!)

Reading the linked chat thread above is starting to give me a vague idea of what this is and why I'd want it, but the README in its current form still leaves me at a bit of a loss for both conceptual understanding (e.g. what are the use cases this thrives in?) and practical understanding (how do I actually use this in my project? And this is coming as someone who's already very familiar with modern Webpack / TS / React / MD / etc tooling)

I have a vague sense this is a _really cool_ thing that'd be useful to me, but it's frustrating I don't have the context I need to understand how this fits in my workflow. I'd love to see a tweaked version of the README that helps make the project more accessible to people like myself who don't already have the deep shared context around this problem space that y'all clearly do.

(As with @scally, please take this as constructive feedback rather than negativity!)

[johno]

This is great feedback, thanks for spending the time to provide it! I've recently started working on a docs branch to address this. It's definitely something we need to improve.

Anyone interested can follow along with the docs branch, and I'll happily accept a PR or any feedback. It's currently very much a WIP.

Also, if you have any ideas on how to best document the usage and motivations for MDX feel free to add to this issue thread and we can work them into the new docs site.

[evangoer]

My quick thoughts, if it helps:

Markdown is good for writing lots of content very quickly. It has simple semantics for paragraphs, headings, lists, blockcode, emphasis, etc., that are easy for devs to remember. Simplicity is great.

However, Markdown’s semantics are too limited for documentation beyond a certain size, say larger than a README. Hence, there are many documentation system built on top of Markdown, and they all add more features & syntax on top. (Alternatively — take a quick look at non-Markdown based documentation systems, to see the kinds of semantics you might want to add.)

Meanwhile, React is great for building apps out extensible components, but bad for writing content. Nobody likes writing thousands of words in raw (X)HTML. It sucks. That’s what “lightweight markup languages” like Markdown and RST were invented for.

MDX gives you the best of both worlds. It lets you write content using Markdown, but freely extensible using React. If JSX is a toolkit for building apps, MDX is a toolkit for building documentation software and other content-heavy projects.

[silvenon]

I think over the time it's become clear enough what the main benefits of MDX are. Over time we'll improve the docs and hopefully clear up remaining mysteries. 😉 Thanks for the feedback everyone!